With stylesheet parameters, you can control:

Here are the parameters that control these features.

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.

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"
        classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
   <param name="Keyword" value="My Title"/>
</OBJECT>

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.

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

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

If manifest.in.base.dir 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 manifest.in.base.dir 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.

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.

Language=0x0409 English (UNITED STATES)

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

java  
    -Dencoding.windows-1252=com.nwalsh.saxon.Windows1252 \
    com.icl.saxon.StyleSheet  \
    myhelpfile.xml  \
    docbook-xsl/htmlhelp/htmlhelp.xsl  \
    htmlhelp.encoding=windows-1252 \
    chunker.output.encoding=windows-1252 \
    saxon.character.representation=native

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:
IDH_opt_installation=install.html

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 htmlhelp.force.map.and.alias parameter to 1 so these files will still listed in the project file.

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

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.

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)”.

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:

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.

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.