Charles Engelke's Blog

Microsoft’s HTML Help is a really nice format for on-line technical
documentation. The information is presented more or less in
HTML, but there are lots of nice additional navigation features
available. For example, not only do you get a table of contents,
as with multiple HTML pages, but you also get an index and a live
search function. And all of this is in a single
CHM file, instead of the
several different files you would have to copy if you were
deploying a multiple HTML page version of the document.

The DocBook XSL stylesheets include a section for HTML help. The
folder c:\Program Files\docbook\xsl\htmlhelp
has an htmlhelp.xsl file in it. We can use
it the same way we used the HTML folder’s
docbook.xsl and chunk.xsl
files:

But this command doesn’t create any
CHM files. Instead, it
created a few HTML files,
and a couple of HHC
files. That’s because CHM
is a proprietary file format, and the stylesheets can’t create
it directly. Microsoft has a tool called the HTML Help
Workshop for creating the files, and the stylesheets created
the source files that the HTML Help Workshop will use. So this
time the DocBook tools didn’t produce the output we want
directly, but they took the first step toward getting the output.
We need to use the HTML Help Workshop to finish the job.

Now we can convert the htmlhelp.hhp and
related files to a single CHM
file using the HTML Help Workshop with the command:

(Yes, that’s very verbose, but we will worry about making everything
more efficient after we get everything to work.)

The resulting file is called htmlhelp.chm and
can be run from the command line with

or from Windows Explorer just by double-clicking. And you can
deploy the document to other machines just by copying that single
file.

We’re going to need to make these tools easier to use, and more
configurable. When we use an XSLT processor to create a single
file, we can control the filename and location. But when using
chunking, as for multiple HTML pages or HTML Help, the stylesheets
create filenames on their own, and put the files in the current
working directory no matter what. We will eventually fix these
problems, but first let’s cover all the main output file formats
we might want from DocBook. There’s one major one left to
produce: Adobe Acrobat Portable Document Format
(PDF). We will create those
files next time.