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.
Creating HTML Help is a two-step process:
Process your DocBook XML document with the DocBook
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.
xsltproc \ ../docbook-xsl/htmlhelp/htmlhelp.xsl \ myhelpdoc.xml
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 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
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 don't have Microsoft's HTML Help Workshop, you can download it for free from http://msdn.microsoft.com/.
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.
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 http://docbook.sourceforge.net/release/xsl/current/doc/html/ in the HTML Help section.
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.
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.
<xsl:param name="htmlhelp.hhp.windows">secondWindow=,"Another Help Window",,\ "furtherHelp.html",,,,,,0x20,,0x4c,[100,200,422,394],,,,,,,0</xsl:param>
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.
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 name||Parameter|
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 button 1||When set to 1, display this button.|
|Specify the text to show below the button.|
|Jump to this URL when pressed.|
|Custom button 2||When set to 1, display this button.|
|Specify the text to show below the button.|
|Jump to this URL when pressed.|
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 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 to the topic's element in your DocBook file, and set the stylesheet parameter
use.id.as.filename to 1. Then the
value will be used as the filename.
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.
htmlhelp.use.hhk parameter controls how your
indexterm elements are converted to index
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
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.
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.
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.
The Help compiler needs to know what language the project files are in, because they don't 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
<l:context name="htmlhelp"> <l:template name="langcode" text="0x0409 English (UNITED STATES)"/> </l:context>
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”.
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 19, 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
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
Saxon 6.5.3 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 -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
These complications are necessary because Saxon 6.5.3 does not itself support that encoding. It is written as a Saxon extension and included with the DocBook XSL distribution.
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.
<chapter id="install"> <?dbhh topicname="IDH_opt_installation" topicid ="1234"?> <title>Installing optional components</title> ...
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,
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 don't have to embed processing instructions in your document to do context-sensitive help. The
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
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 aren't changing the DocBook document, only the parameters used to configure the Help files. The default value is 0.
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.
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 are 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.
[ALIAS] #include alias.h [MAP] #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.
The primary areas of controlling formatting for HTML Help are:
These are described in the sections that follow.
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.
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.
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.
To create customized headers and footers, see the section “HTML headers and footers”.
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.
docbook-apps mailing list, which has many active users of DocBook HTML Help who can answer questions.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises