Jirka
Kosek
2001
Ji&rcaron;í Kosek
$Id: htmlhelp.xml,v 1.1 2002/05/15 17:22:31 isberg Exp $

# Using XSL stylesheets to generate HTML Help

HTML Help (HH) is help-format used in newer versions of MS Windows and applications written for this platform. This format allows to pack several HTML files together with images, table of contents and index into single file. Windows contains browser for this file-format and full-text search is also supported on HH files. If you want know more about HH and its capabilities look at HTML Help pages.

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

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

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

If you are using XT processor, you should use stylesheet `xthtmlhelp.xsl` instead of `htmlhelp.xsl`.

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

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

Title of whole HH file is taken from first title element in your document. Fulltext searching is automatically on. If your document contains index terms, they are automatically converted to HH ActiveX objects, which are recognized by HTML Help compiler.

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

    hhc htmlhelp.hhp

If you can not stand without your mouse, there is alternative way. Just double-click on `htmlhelp.hhp` file. HH Workshop will be launched automaticaly. Generation of HH file can be started by selecting File Compile from application's menu.

## Customizing generated files

### Enabling navigation links

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

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

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

    <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="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 output encoding of your files, because HTML Help compiler improperly handles UTF-8 and even character entities in TOC file and index entries. This can be easily done by 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).

## Feedback

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