HTML Help is a version of HTML suitable for generating help documents for Microsoft Windows. You can write your help information in DocBook XML, and generate HTML Help files using a customized DocBook XSL stylesheet that is included with the distribution.

Generating HTML Help

Creating HTML Help is a two-step process:

  1. Process your DocBook XML document with the DocBook htmlhelp.xsl stylesheet.

  2. Compile the resulting files with a HTML Help compiler, either from Microsoft or a third party.

In the first step, you process your DocBook help document like you would for chunked HTML, but with a customized version of the chunking stylesheet. The customized stylesheets are located in the htmlhelp subdirectory of the stylesheet distribution. You use one of these stylesheets with your favorite XSLT processor:


The main stylesheet file for generating HTML Help output.


A further customization that supports profiling to filter your DocBook XSL files before generating output.

For example:

xsltproc \
   ../docbook-xsl/htmlhelp/htmlhelp.xsl \

The output of this process is a collection of HTML files and some non-HTML files. The HTML files are chunked HTML files with the navigational headers and footers removed. In fact, you can use all of the stylesheet parameters and customizations you would normally use when generating chunked HTML.

The non-HTML files provide information to the HTML Help compiler. These files include:


The HTML Help project file lists compile options, the size and location of the help window, and a list of HTML files to be included.


The contents file provides the information for creating the left pane table of contents in HTML Help. It uses nested UL lists to indicate structure, and includes the section titles and HTML filenames so links will work.


The HTML Help index file. This file will contain index entries if your document contains DocBook indexterm elements and you set the htmlhelp.use.hhk parameter to 1. See the section “Generating an index” for more information.

alias.h, context.h

Optional files, generated if you are doing context sensitive help. See the section “Context-sensitive help” for more information.

The filenames can be changed with stylesheet parameters, as described in the section “Filenames and locations”. Once you have generated the set of files, you can compile them into HTML Help. There are several options for that:

  • Start Microsoft's HTML Help Workshop application, and use the File menu to open the htmlhelp.hhp project file. It should list the contents, and provide you with an option to compile it. If you do not have Microsoft's HTML Help Workshop, you can download it for free from

  • Use Microsoft's command line compiler hhc.exe with the project file as its first argument. The compiler is included with Microsoft's HTML Help Workshop.

  • Use a third-party HTML Help compiler.

Processing options

The DocBook HTML Help stylesheets let you control various options by setting stylesheet parameters. Each parameter has a reference page that is included with the distribution documentation, and can also be reached online at in the HTML Help section.

Display options

With stylesheet parameters, you can control:

  • The help window title, size and position.

  • Whether the help menu appears.

  • Which standard toolbar buttons are displayed.

  • Adding custom toolbar buttons.

Here are the parameters that control these features.

Window options

The Help application title to display in the window's title bar.


Set the size and position of the HTML Help window when it opens. Its value looks like the following:


The first two numbers indicate the position of the upper-left corner of the window, and the second two numbers the position of the lower-right corner. All numbers are in pixels, measured from the upper-left corner of the screen. So this example creates a window that is 832 pixels wide (992 - 160) and 640 pixels tall, positioned 160 pixels from the left edge and 64 pixels down from the top.


If set to 1, the Help window will restore its last size and position when it starts again., htmlhelp.hhp.window

These two parameters help you create additional windows for your HTML Help application. The first parameter lets you create additional windows for the Help application. For example:

<xsl:param name="">secondWindow=,"Another Help Window",,\

The content of the parameter is appended to the [Windows] section of the generated project file. The second parameter tells the application which is the default window to use when opening. It should be a window name as defined in the project file. To put content or links into the secondary windows, you need to customize the XSL stylesheet to insert script code in the HTML files. See the Microsoft's HTML Help documentation to see what code to insert. See the section “Inserting external HTML code” for an example of inserting code in DocBook-generated HTML.

Display the menu

If set to 1, the Help application will have the standard menus at the top. Otherwise, there is no menu and navigation is done by buttons only.

Display standard buttons and tabs

You can select which toolbar buttons are displayed in your Help application. Each parameter controls one button. Set its value to 1 to display the button, or to zero to hide it. The following table lists the button parameters.

Standard button nameParameter

Another parameter,, turns on or off the text labels that appear below the buttons.

Create custom buttons

You can add one or two buttons that link to HTML pages outside of the Help application. These buttons are called jump buttons, and each one has three parameters: to display the button, to label the button, and to identify the link for the button. The following table lists the parameters that control the custom buttons.

Custom buttonParametersDescription
Custom button 1htmlhelp.button.jump1When set to 1, display this button.
htmlhelp.button.jump1.titleSpecify the text to show below the button.
htmlhelp.button.jump1.urlJump to this URL when pressed.
Custom button 2htmlhelp.button.jump2When set to 1, display this button.
htmlhelp.button.jump2.titleSpecify the text to show below the button.
htmlhelp.button.jump2.urlJump to this URL when pressed.

Table of contents pane

The following parameters let you control various aspects of the table of contents window pane that appears to the left of the Help text. That pane shows an expandable table of contents for the Help content.

If set to 1 (the default), then the top level of the TOC list is the book title. Since this single entry at this level is often redundant with the window frame title, it is frequently set to zero, which shows a longer list of topics to choose from.


Specifies the width of the TOC pane, in pixels. If not set, then you get the default width.


If set to 1, displays numbering of chapters and sections in the TOC pane if they are numbered in the content. This feature is off by default.


Specifies how many levels of nested sections to include in the TOC pane. Set to 5 by default, which means all section levels are included.


Specifies the HTML chunk filename to be displayed in the right-hand pane when the Help window opens. If not specified, then it takes the chunk generated by the root element of the document, which is usually index.html. Since this chunk usually repeats the table of contents that is already being shown in the left pane, it is not uncommon to choose the first real content chunk for this parameter.

To get a stable chunk filename to point to, add an id attribute (or xml:id for DocBook 5) to the topic's element in your DocBook file, and set the stylesheet parameter to 1. Then the id or xml:id value will be used as the filename.

If set to 1, then a Favorites tab is added to the top of the TOC pane. The Favorites pane lets the reader save bookmarks into the Help file. The default is zero.

If set to 1, then the Search pane has more advanced search options. If set to zero (the default), then the Search pane has just basic search options.


If set to 1 (the default), then the TOC list displays icons that look like folders instead of books. Note that this parameter has no effect if the htmlhelp.hhc.binary is set to 1.


If set to 1 (the default), it compiles the TOC into a binary form to improve performance. This setting also enables the Next and Previous buttons.

Generating an index

When you generate your HTML Help using DocBook XSL, your Help file will have an Index tab in the TOC pane that contains all the titles in your document. That is the minimum index that can be generated. They appear because the stylesheet embeds code like the following in the HTML output for each title:

<OBJECT type="application/x-oleobject"
   <param name="Keyword" value="My Title"/>

If your DocBook document contains indexterm elements, then those will also automatically be converted to entries in the Help index.

The htmlhelp.use.hhk parameter controls how your indexterm elements are converted to index entries. If htmlhelp.use.hhk is set to zero, then the stylesheet inserts an OBJECT element similar to the above example into the HTML output for each indexterm. If the parameter is set to 1, then the terms are instead put into the index.hhk file. You will still get a index.hhk file if the parameter is set to zero, but it will be almost empty. You can ignore the warning issued by the compiler about the empty file.

The advantage of putting the index entries in the separate index.hhk file is that the links to the index terms will go to the exact location in the HTML file, instead of to the top of the topic. Unfortunately, if there are multiple occurances of the same index term, the index list will display the term instead of the topic titles (this is a bug in HTML Help). There is no known workaround for this problem, except to leave the parameter value at zero and accept links going to the top of the topic.

Filenames and locations

Each of the non-HTML files that are generated by the stylesheet can have its filename changed by its own parameter.


Change the filename of the project file from the default htmlhelp.hhp. You should retain the .hhp suffix so the compiler can recognize the file type.


Change the filename of the table of contents file from the default toc.hhc.


Change the filename of the help index file from the default index.hhk.


Change the filename of the compiled Help file from the default htmlhelp.chm. This file is generated by the compiler, but its name is specified in the project file.

Change the filename of the optional context-sensitive help map file from the default context.h.


Change the filename of the optional context-sensitive help alias file from the default alias.h.

In addition to specifying the filenames, two more parameters control where the HTML files are generated.


This standard chunking parameter lets you add a directory prefix to all the HTML files generated by the chunking process.

If this parameter is set to 1, then the non-HTML Help files such as htmlhelp.hhp are also placed in the directory specified by the base.dir parameter.

If is set to 1, then all your files end up in the same directory, the one specified by the base.dir parameter. Also, all references to the files from the htmlhelp.hpp project file will have no path prefix. Because they are in the same directory as the project file, the Help compiler will find them.

If is set to 0 (the default), then your non-HTML files end up in the current directory. All references to HTML files from the htmlhelp.hpp project file will have the base.dir path prefix added to them so the compiler can find them. The Help file will build with either configuration, so it is mostly a matter of your preference for managing files.

If you use a CSS stylesheet to style your HTML, you will have to copy it manually to the directory specified by the base.dir parameter. The same is true for any image files.

Language and encoding

If you are processing non-English files, there are two features of the stylesheets you need to consider.

Even if you are processing English files, you need to consider the encoding in order to get all the special characters you might be using in your document.

HTML Help language

The Help compiler needs to know what language the project files are in, because they do not have any encoding identifiers like the HTML files do. That information is supplied by a Language property in the htmlhelp.hhp project file, as for example:

Language=0x0409 English (UNITED STATES)

That property is inserted into the project file by the stylesheet based on the root element's lang attribute in your DocBook document. If there is no lang attribute on the root element, then en is used. The actual text string is taken from the gentext file for that language, such as common/en.xml:

<l:context name="htmlhelp">
   <l:template name="langcode" text="0x0409 English (UNITED STATES)"/>

If the wrong value is inserted, then you will likely get mangled output. If for some reason you need a language string that is different from the one supplied by the stylesheet for your language, you can customize the gentext template, using the process described in the section “Customizing generated text”.

HTML Help encoding

You must also consider the character encoding of the HTML files that are generated by the stylesheet. For a general discussion of encoding, see Chapter 20, Languages, characters and encoding.

The encoding of the HTML output has to be one that your Help compiler recognizes. The UTF-8 encoding covers most languages and special characters. Unfortunately, the Microsoft Help compiler does not recognize UTF-8 encoding. Some of the third-party Help compilers do support UTF-8. If you are using the Microsoft compiler, two encodings that are often used are iso-8859-1 and windows-1252.

You can establish the output encoding of the stylesheet using the htmlhelp.encoding parameter, which is set to iso-8859-1 by default. That encoding covers the basic European languages, but does not contain some special characters such as longer dashes, typographical quotes, or the ™ or Euro symbols. The windows-1252 encoding is identical to iso-8859-1 over most of its range, but includes more special characters, including trademark and euro.

If you want to use windows-1252 as your output encoding, you have to consider what XSLT processor you are using. The xsltproc processor can output windows-1252, as can any XSLT processor that implements the EXSLT document() extension function. On the other hand, Xalan does not support changing the output encoding for chunked files, so it cannot output windows-1252.

Saxon 6.5.5 can output the windows-1252 encoding under the right conditions. You must use the DocBook Saxon extension file from version 1.67 or later of the stylesheets. To do that, you add the extensions/saxon653.jar file from the stylesheet distribution to your CLASSPATH. You must also set three stylesheet parameters and a Java property for it to work:

java \
    com.icl.saxon.StyleSheet  \
    myhelpfile.xml  \
    docbook-xsl/htmlhelp/htmlhelp.xsl  \
    htmlhelp.encoding=windows-1252 \
    chunker.output.encoding=windows-1252 \

These complications are necessary because Saxon 6.5.5 does not itself support that encoding. It is written as a Saxon extension and included with the DocBook XSL distribution.

Context-sensitive help

If you intend for your Help file to be used for context-sensitive help with an application, you must provide additional information in your DocBook document. The additional information provides the connections between points in your application and points in your document, so that help requests return context-sensitive help.

The extra information is added in the form of processing instructions. For example:

<chapter id="install">
  <?dbhh topicname="IDH_opt_installation" topicid ="1234"?>
  <title>Installing optional components</title>

The IDH_opt_installation is a unique identifier string for this help topic, and the 1234 topicid is a unique number that can be added to your application to find that topic.

When you process your document with htmlhelp.xsl, you will find two new non-HTML files generated, context.h and alias.h. They will contain lists of the information you provided in the processing instructions:

In context.h:
#define IDH_opt_installation  1234

In alias.h:

These two files are identified in the htmlhelp.hhp project file properties in the [MAP] section and the [ALIAS] section, respectively. See the Microsoft HTML Help API reference for more information about using context-sensitive help topics in your application.

You do not have to embed processing instructions in your document to do context-sensitive help. The context.h and alias.h files can be written by hand, perhaps based on information provided by the software application developer. You can then set the parameter to 1 so these files will still listed in the project file.

Build options

There are a few stylesheet parameters that control features of the build process.


If set to 1, then the stylesheet builds only the non-HTML files. This is useful when you are not changing the DocBook document, only the parameters used to configure the Help files. The default value is 0.


If set to 1 (the default), then the compile displays its progress as it goes.


If you have special content you need to add to the end of your project file, then put that content into this parameter. Whatever is there will be appended to the htmlhelp.hpp file each time the stylesheet is used.


When set to 1, allows for enhanced decompilation for your .chm help file. The default is zero.


If set to 1, then the pathnames of all the images used in the document are added to the project file's [FILES] section. This is not necessary if your images all use relative fileref attributes in your DocBook file to find them, and they are located in the same directory or a subdirectory of the project file location. But if they use absolute paths, are located outside the project directory tree, or if they use entityref in the DocBook file, then you should turn on this parameter to help the compiler find the files. The default value is 0.

If set to 1, then the stylesheet will add the following lines to the project file, even if you have no dbhh processing instructions in your document.

#include alias.h
#include context.h

These files are used for context-sensitive help. Set this parameter to 1 when you will be creating or enhancing these files manually.

Formatting options

The primary areas of controlling formatting for HTML Help are:

These are described in the sections that follow.

Chunking control

Online help is usually presented in small chunks of content rather than long scrolling files. You should consider to what level of section depth you should chunk your content, in order to keep the chunks small but not so small that they contain too little information.

Because the htmlhelp.xsl stylesheet is a customization of the chunk.xsl stylesheet, you can use all of that stylesheet's parameters to configure the chunking behavior.


The maximum section depth that will become a chunk. If set to 1 (the default), then all sections at level 1 become a chunk, and any sections at higher levels are contains as subsections within their chunk. If set to 2, then all sections at levels 1 and 2 become chunks, and so on.


If set to 1, then the first section in each chapter becomes a chunk. If set to zero (the default), then the first section is part of the beginning-of-chapter chunk.


Determines the name of the top-level chunk filename (without the suffix). It is index by default.

If set to 1, then the HTML filename uses the element's id or xml:id attribute as the first part of the filename. The default is zero.


Determines the filename suffix for each generated HTML file. The default is .html (include the dot).


If set to 1, then the top level table of contents and any lists of titles (such as List of Figures) are put into a separate chunk. The default is zero.


If set to 1, then each list of titles (such as List of Figures, List of Tables, etc.) is put into its own chunk, and a link to each is added under the table of contents. The default is zero.


If set to 1, then the top level table of contents chunk displays a repeat of the top level title. The default is zero.

Tables of contents

You may want to turn off all tables of contents in the HTML content, because the Help TOC frame on the left provides that information. If you turn off TOCs in the content, then that information is not repeated in the content pane on the right. The easiest way to turn off all TOCs in content is to set the generate.toc parameter to an empty string.

If instead you want to customize how TOCs are rendered in content, then see the section “Tables of contents (TOC)”.

Section numbering

You can turn on chapter or section numbering using standard DocBook stylesheet parameters, as described in the section “Chapter and section numbering”. By default, the chapter and section numbers that appear in the right content pane do not appear in the left TOC pane in the Help viewer. This parameter turns them on:


If set to 1, includes the numbers of chapters and sections in the TOC pane. This feature is off by default. It will only display numbers of items are numbered in the content.

CSS styles

HTML Help supports using a CSS stylesheet for controlling formatting of the displayed content. The CSS code must be compatible with the Internet Explorer browser that will be used to read the help file. The basic process of writing and using a CSS stylesheet with DocBook is described in the section “Using CSS to style HTML”. To ensure that your stylesheet is included in the Help file, you must set the html.stylesheet parameter to the name of the file. That will put a LINK element in each HTML file, and the compiler will include the referenced stylesheet in the compiled Help file.

If your CSS file references other files, such as graphical icons, then those are not automatically detected, and will need to be added to the project's file list. That can be done with the htmlhelp.hhp.tail parameter that can contain another [Files] section to be added to the end of the project file.

Headers and footers

The HTML Help customization turns off the regular chunk headers and footers in the output. Those headers and footer provide navigation links that are instead provided by the Help interface. However, you can turn them back on, or you can substitute your own through parameters and customization.

  • To restore the normal chunk headers and footers, then set the suppress.navigation parameter to zero. It is set to 1 by default to turn them off in HTML Help.

  • To create customized headers and footers, see the section “HTML headers and footers”.

Additional resources

Here are some additional resources when working with DocBook HTML Help:

  • Dave Pawson's HTML Help FAQ.

  • Microsoft's help files for HTML Help Workshop. You can sometimes make a change to a project using the Workshop interface, and then examine the project file to see what changed. You could then incorporate those changes into a parameter or customization of the XSL stylesheet.

  • The docbook-apps mailing list, which has many active users of DocBook HTML Help who can answer questions.