Jirka
Kosek
2001
Ji&rcaron;í Kosek
$Id: htmlhelp.xml,v 1.1 2003/06/09 18:40:44 blackburst Exp $

# Using the XSL stylesheets to generate HTML Help

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.

## How to generate your first HTML Help file from DocBook sources

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.

## Customizing generated files

### Enabling navigation links

By default, the HTML Help stylesheet disables navigation links at the start and the bottom of each page. If you want to enable the links instead, start your XSLT processor with the parameter `suppress.navigation` set to 0.

    saxon yourfile /path/to/stylesheets/htmlhelp/htmlhelp.xsl "suppress.navigation=0"

Another approach is to create a driver file, which overrides the default parameter value.

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    	        version="1.0">

      <xsl:import href="/path/to/stylesheets/htmlhelp/htmlhelp.xsl"/>

      <xsl:param name="suppress.navigation" select="0"/>

    </xsl:stylesheet>

### Generating HTML Help for non-Western European languages

If you are generating HTML Help for non-Western Europe languages, you should change the output encoding of your files, because the HTML Help compiler improperly handles UTF-8 and even character entities in the TOC file and index entries. This can be easily done using a driver file like this:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    	        version="1.0">

      <xsl:import href="/path/to/stylesheets/contrib/htmlhelp/htmlhelp.xsl"/>

      <xsl:param name="htmlhelp.encoding" select="'windows-1250'"/>
      <xsl:param name="default.encoding" select="'windows-1250'"/>
      <xsl:param name="saxon.character.representation" select="'native'"/>

    </xsl:stylesheet>

Default encoding is ISO-8859-1 (aka ISO Latin 1). If you get some strange message about characters from your XSLT processor and your document is in some of Western European languages, try changing encoding to `windows-1252`. This encoding is similar to ISO-8859-1 but contains some additional characters like typographical quotes and dashes.

### More about customizing

More info will come in a near future (I hope and believe). Meanwhile look into reference for description of HTML Help specific parameters.

## Feedback

If you have any comments and suggestions about the HTML Help stylesheet feel free to contact me at following address jirka@kosek.cz.