Charles Engelke's Blog

February 8, 2004

DocBook to HTML Help

Filed under: docbook — Charles Engelke @ 10:58 pm

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

java -jar "c:\Program Files\docbook\saxon\saxon.jar" \
sample1.docbook \
"c:\Program Files\docbook\xsl\htmlhelp\htmlhelp.xsl"

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.

Procedure 3.3. Installing the HTML Help Workshop.

  1. Download the latest version of the
    Help Workshop
    to a temporary directory. Microsoft
    moves things around all the time, so that link might not
    work for you. Google html help workshop
    to find it.

  2. Run the htmlhelp.exe file you just
    downloaded. Follow the directions to install the program.
    We assume that the program is installed in the
    c:\Program Files\HTML Help Workshop

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

"c:\Program Files\HTML Help Workshop\htmlhelp" htmlhelp.hhp

(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

start htmlhelp.chm

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

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.


Blog at

%d bloggers like this: