Jirka Kosek

$Id: htmlhelp.xml,v 1.2 2003/10/29 11:48:18 kosek Exp $

How to generate your first HTML Help file from DocBook sources
Customizing generated files

HTML Help (HH) is a help format used in newer versions of Microsoft Windows and applications written for that platform. The HTML Help format allows you to pack several HTML files together with images, a table of contents, and an index into a single file. Windows contains a browser for this file format and full-text search is also supported on HH files. If you want to know more about HH and its capabilities, visit the Microsoft HTML Help Start Page.

Working with the HH stylesheets is the same as with other XSL DocBook stylesheets. Simply run your favorite XSLT processor on your document with the HH stylesheet:

saxon yourfile /path/to/stylesheets/htmlhelp/htmlhelp.xsl

The stylesheet imports the standard chunking stylesheet, so a set of HTML files is created in the usual way. Other files are also created – htmlhelp.hhp is the project file for the HTML Help Compiler and toc.hhc holds the structure of your document.

The language identifier for the overall HH file is taken from the top-most element with a lang attribute in your DocBook source. This is perfectly legal for documents in only one language. If a language is not specified in the document, US English is used. There is one problem – MS language codes are country-sensitive, and this information is not available in the DocBook source. If the stylesheet selects a bad code for you, edit langcodes.xml, and remove all entries which have your language code, but are located in an inappropriate country.

The title for the overall HH file is taken from the first title element in your document. Full-text searching is automatically on. If your document contains index terms, they are automatically converted to HH ActiveX objects, which are recognized by the HTML Help compiler.

The stylesheet creates couple other files which are then used as an input for the HTML Help Compiler (HHC), which is part of HTML Help Workshop. If you have HHC in your path, you can start conversion to the HH format by running this command:

hhc htmlhelp.hhp

If you cannot stand to work without using your mouse, there is alternative way. Just double-click on the htmlhelp.hhp file. HH Workshop will be launched automatically. Generation of the HH file can be started by selecting File->Compile from the application's menu.