Webhelp adventures: the gory details

Hi, all.

In my excessively long "Adventures in Webhelp" note, I offered to provide
some of the customizations I did to interested parties. I have attached
three stylesheets and one Perl script. (This note probably won't make much
sense if you haven't read that prior one, since I refer to issues noted there.)

I have attached the stylesheet I use to generate a single, generic sidebar
TOC into a file as a preprocessing step. This is not dependent on any of
the webhelp stylesheets, though it consists of the TOC-building template
from webhelp. The main stylesheet is the one that contains the customizations
I made for generating the chunked HTML. This is where I refactored some of
the templates, parameterized some of the customization hooks that weren't
parameterized, and otherwise overrode a bunch of webhelp-common.xsl.
The third simply contains my modified "object.id" template, which is imported
into the other two.

The Perl script is run as a preliminary step for doing search indexing.
It has two main jobs: fixing that unclosed meta tag (Content-Type) (which
is what I wrote it for originally), and adding "webhelp-currentid" at the
right place in each file's copy of the sidebar TOC.

Note that these are NOT exactly the version we use, since I have
stripped out some non-webhelp-related customizations, and some "corporate"
branding things. (The only one that's substantially different is the HTML chunking
XSL. The rest were so small and generic that there wasn't really
much to remove. But all the "webhelp"-related stuff is here.)

I've also attached a screen shot that shows what our webhelp looks like.
The content is the README from the DocBook webhelp itself.

Here is the basic build sequence we use. We have a TON of Ant scripts,
and I'm not going to try and provide them, since they are highly specific
to our environment, and not easily "genericized". I'll be happy to answer
any questions about what the steps do, but most of this is straightforward
if you've got webhelp already building.

A couple of things to note:

  * The <book> documents we wrap into <set>s are all stand-alone, so we are
    NOT doing o-linking between them. There are no passes
    to generate target databases.

  * We are also NOT profiling.

This is what we do for each of our "helpset" documents (XML <set> files
that xinclude one or more <book> documents):

1. Delete any old output tree, and create a new output tree. This will
   be zipped up for installation with the product. (This structure
   is basically the webhelp template, with some additional directories
   for our product images.)

2. Copy our CSS file into the expected location in the output tree.

3. Copy our doc-related graphics into the output tree. This includes our
   content graphics, admonition icons, and HTML-specific icons.

4. Copy the parts we are using from the DocBook Webhelp template
   into the output tree. We skip a lot of the "common" images (because
   we replace them with our own in the next step), and some of the JS library
   images (like callouts), which we just don't use or need.

5. Copy our modifications to the DocBook Webhelp template
   into the output tree. This is mostly images, but we also have a
   modified version of "main.js" (we commented out a block of code
   as a solution to a problem with within-page links, and we changed
   some of the hard-coded colors. No other changes were made).

6. Generate the generic sidebar TOC using XSLTproc and "mt-webhelptoc.xsl".

7. Generate the webhelp HTML files using XSLTproc and "mt-wehbelp.xsl".
   This step splices a copy of the generic sidebar TOC into each file.

8. Generate the search indices. This actually is three steps:

   First, we run the "post-process-html" Perl script on the HTML files.
   This fixes an issue with an unclosed "meta" element and adds the
   "webhelp-currentid" to the right place in the generic sidebar TOC for
   the file being processed.

   Second, we run the "IndexerMain" class from the DocBook stylesheets.

   Third, we delete the temp files generated during search indexing but
   not used in running searches.

The output tree is then zipped up for installation with the product.

Again, I do not suggest that the customizations I have made are in any
way suitable for general-purpose use, but perhaps they may inform some
discussion for possible refinements. I hope someone finds this at least
interesting. Feel free to contact me directly if you want

Thanks for hanging with me this long!

-- Mary