HTML Help Files

Michael Smith

Jirka Kosek has created an XSLT stylesheet driver file for generating HTML Help and continues to add features/parameters to it as they get requested. The stylesheet driver file and Jirka's short tutorial on using it are included in the standard DocBook docbook-xsl stylesheet distribution in the htmlhelp subdirectory.

A copy of Jirka's "Using the XSL stylesheets to generate HTML Help" tutorial is available at: sourceforge

To download the latest docbook-xsl stylesheet distribution.

Jirka Kosek

Starting from next release documentation will be in a common xsl/doc directory. An HTML version of file will be accessible at Sourceforge.

Jirka Kosek

You have TM character in your document. In order to process all HTML Help files, you shouldn't have any numeric character references in your HTML and project files. Default encoding used for output is ISO-8859-1 which doesn't contain TM character. You must use different encoding -- I think that windows-1252 will be suitable. To do it, just pass another 3 parameters to stylesheet (or set them in customization layer): saxon doc.xml .../htmlhelp.xsl "default.encoding=windows-1252" "htmlhelp.encoding=windows-1252" "saxon.character.representation=native"

Jirka Kosek

there is a new parameter in CVS version of XSL stylesheets. If you set htmlhelp.hhc.show.root to 0, there will be no entry for the root element in ToC in a left pane. This means that user will see titles of nested elements (usualy chapters) directly.

Another new parameter is htmlhelp.default.topic. You can use it to change default topic to display (parameter expects filename of HTML chunk).

Steffen Maier

"The attributes on xsl:output elements affect only the main result document." [http://www.w3.org/TR/xslt11/#multiple-output] For chunked output dbxsl makes use of one of the following elements, depending on available xslt-extensions: <exsl:document>, <saxon:output> or <xalanredirect:write>. XSLT 1.1 WD suggests the similar <xsl:document>.

IMO, you need to specify omit-xml-declaration="yes" in just those mentioned elements so they apply to every single written junk. They are used inside chunker.xsl in the named template write.chunk.

According to http://saxon.sourceforge.net/saxon6.5/doc/xsl-elements.html#xsl:document the use of xsl:output attributes should be possible, e.g. for <saxon:output>.

Concerning the main result document there should be no need to modify the xsl:output's in imported stylesheet fragments because they are already overridden by your customization layer.

David Cramer

I put a (fairly simple) customization of the htmlhelp xsls in the contrib directory. It allows you to generate cross platform help that works on most browsers that can run applets, and you can still generate a chm from the same html help project. For the applet-based help to work, you have to get some class files etc. from the html help workshop directory and put them with the frameset files that the xsl generates.

Known issue: for the index tab to work you have to turn on htmlhelp.use.hhk, but the index that's generated with the applet isn't as nice as the one in the chm. In fact, it isn't even sorted (apparently the chm does that automatically), so I need to figure out what to do to the generated hhk file to make it work for this applet based help.

There's no search or favorites tab, but apparently some other ActiveX-stuff, like html help Related Topics buttons would work if it were included.

Here's a demo of the output: thingbag.net

The files: sourceforge CVS

Let me know if you have any questions or problems. I'd be interested to hear what browsers/platform combinations it does and doesn't work on. The output works on Opera 6/7 on Win2k, IE 5.5 and 6 on Windows, Opera 6 and Netscape 4.7 on Linux, IE 5.x on Mac OS X and 9.x (Netscape 4.7 on Mac 9.x crashed, however), and Netscape 7 on Windows and Mac OS X.

Jirka Kosek

You must also set htmlhelp.button.jump1 to 1 and htmlhelp.button.jump1.title to some reasonable title for button.

Just ignore this message. Compiled help will work.

E.g. HTML Help version of TDG uses this setting:

<xsl:param name="htmlhelp.button.jump1" select="1"/>
<xsl:param
name="htmlhelp.button.jump1.url">http://sourceforge.net/docman/display_doc.php\
?docid=10513&amp;group_id=21935</xsl:param>
<xsl:param name="htmlhelp.button.jump1.title">Archives</xsl:param>

Jirka Kosek

Set parameter htmlhelp.encoding to the name of encoding which contains TM chatacter. I think that following should work:

<xsl:param name="htmlhelp.encoding">windows-1252</xsl:param>

Jirka Kosek

If you set

<xsl:param name="htmlhelp.hhc.show.root" select="0"/>

you will get what you want, except that instead of TitlePage you will see text Table Of Contents. To change this to your text, you must add following template into your customization layer (changes are near to ***TitlePage*** text):

<xsl:template match="book" mode="hhc">
   <xsl:variable name="title">
     <xsl:if test="$htmlhelp.autolabel=1">
       <xsl:variable name="label.markup">
         <xsl:apply-templates select="." mode="label.markup"/>
       </xsl:variable>
       <xsl:if test="normalize-space($label.markup)">
         <xsl:value-of 
            select="concat($label.markup,$autotoc.label.separator)"/>
       </xsl:if>
     </xsl:if>
     <xsl:call-template name="escape-attr">
       <xsl:with-param name="value">
         <xsl:apply-templates select="." mode="title.markup"/>
       </xsl:with-param>
     </xsl:call-template>
   </xsl:variable>

   <xsl:if test="$htmlhelp.hhc.show.root != 0 or parent::*">
     <xsl:text 
          disable-output-escaping="yes">&lt;LI&gt; &lt;OBJECT 
         type="text/sitemap"&gt;
       &lt;param name="Name" value="</xsl:text>
           <xsl:value-of select="normalize-space($title)"/>
       <xsl:text disable-output-escaping="yes">"&gt;
       &lt;param name="Local" value="</xsl:text>
           <xsl:call-template name="href.target.with.base.dir"/>
       <xsl:text disable-output-escaping="yes">"&gt;
     &lt;/OBJECT&gt;</xsl:text>
   </xsl:if>
   <xsl:if test="part|reference|preface|chapter|appendix|
         bibliography|article|colophon|glossary">
     <xsl:variable name="toc.params">
       <xsl:call-template name="find.path.params">
         <xsl:with-param name="table" 
select="normalize-space($generate.toc)"/>
       </xsl:call-template>
     </xsl:variable>
     <xsl:text 
       disable-output-escaping="yes">&lt;UL&gt;</xsl:text>
       <xsl:if test="contains($toc.params, 'toc') and 
$htmlhelp.hhc.show.root = 0 and not(parent::*)">
         <xsl:text 
 disable-output-escaping="yes">&lt;LI&gt; &lt;OBJECT 
type="text/sitemap"&gt;
           &lt;param name="Name" value="***TitlePage***"&gt;
           &lt;param name="Local" value="</xsl:text>
               <xsl:call-template name="href.target.with.base.dir"/>
           <xsl:text disable-output-escaping="yes">"&gt;
         &lt;/OBJECT&gt;</xsl:text>
       </xsl:if>
       <xsl:apply-templates 
select="part|reference|preface|chapter|bibliography|appendix|article|
        colophon|glossary"
			   mode="hhc"/>
     <xsl:text 
    disable-output-escaping="yes">&lt;/UL&gt;</xsl:text>
   </xsl:if>
</xsl:template>

Jirka Kosek

You can control where and how is ToC generated by using generate.toc parameter. For your situation the following setting should work:

<xsl:param name="generate.toc">
set	title,toc
book	nop
article	nop
</xsl:param>

David Cramer

You could test for: substring(//*/@lang[1],1,2) = 'ja'

That will use the first lang attribute it finds in the doc.

<xsl:param name="htmlhelp.encoding">
 <xsl:choose>
   <xsl:when test="substring(//*/@lang[1],1,2) = 'ja'">Shift_JIS</xsl:when>
   <xsl:otherwise>window-1252</xsl:otherwise>
 </xsl:choose>
</xsl:param>