oXygen XML Editor

HTML Help Files

1. How to convert Docbook into Microsoft Windows help files
2. Where is the documentation?
3. Character Encoding problems
4. Configuration parameters
5. xml declaration in html help
6. HTML help customisation
7. htmlhelp.button.jump1.url parameter
8. Help file encoding
9. HTML Help title page
10. HTML Help table of contents
11. Testing for language in CHM files

1.

How to convert Docbook into Microsoft Windows help files

Michael Smith


> I need to write a programmer's manual for a bunch of Windows
> programmers, and I'd like to use DocBook.  Previously, they have all
> used Microsoft Word.

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 tutorial is available at: Bob Staytons site

To download the latest docbook-xsl stylesheet distribution.

2.

Where is the documentation?

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.

3.

Character Encoding problems

Jirka Kosek



> I'm getting the following strange error from the htmlhelp stylesheets
> using Saxon using v. 1.44 of the stylesheets. Xalan does get through it:

> Writing index.html for article
> Writing htmlhelp.hhp
> Writing toc.hhc
> Error on line 117 of
> file:/H:/Work/xmldocs/export/DocBookXSL/1.44/html/chunker.xsl:
>   Output character not available in this encoding (decimal 8482)
> Transformation failed: run-time errors were reported
> Error, could not complete transformation

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"

4.

Configuration parameters

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

5.

xml declaration in html help

Steffen Maier


>  For html
> help, however, hhc.exe doesn't like the xml declaration and complains
> about it on each html page it compiles:

> HHC3004: Warning: go01.html : The HTML tag "?xml version="1.0"
> encoding="ISO-885
> 9-1"?" is not a valid HTML tag (it does not begin with an alphanumeric
> character
> ).


> doesn't really say why it's quitting). I'm trying to keep the xml
> declaration from appearing in the output by adding <xsl:output
> method="xml" omit-xml-declaration="yes"/> to my customization layer, and
> even just changing the xsl:output elements from xhtml/docbook.xsl and
> xhtml/calc-chunks.xsl in the distribution (those are the only ones I
> found). 

> What am I missing?

"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.

6.

HTML help customisation

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.

7.

htmlhelp.button.jump1.url parameter

Jirka Kosek



> I've tried using something such as:
> <xsl:param name="htmlhelp.button.jump1.url" 
>     select="'http://www.linux.org'"/>

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


> but it raised the following error in the HTML Help Workshop Compiler:
> HHC5003: Error: Compilation failed while compiling http:\www.linux.org.

Just ignore this message. Compiled help will work.


> Where does the URL go on that param ? Can someone please point me a
> working example using a real-world URL ?

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>

8.

Help file encoding

Jirka Kosek


> The encoding for my document is ISO-8859-1 and if I remove the trademark
> sign it works. Anybody knows how to solve this?

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>

9.

HTML Help title page

Jirka Kosek


>   In some .chm deliverables created from
> RoboHelp and in some others that I've seen on the net,
> there is an actual topic-icon named title-page and
> sometimes a "what's new" page included at the root
> level in the .chm's left, TOC pane.  Below it are all
> the chapter-icons that look like books and coorespond
> to chapters.  Clicking on the titlepage topic brings
> you back to the titlepage just as the home button
> does.

> They look like this in the chm's TOC:

> [topic icon] TitlePage
> [topic icon] What's New
> [Chapter icon] Introduction
> [Chapter icon] Installation Procedure
> ...etc

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>

10.

HTML Help table of contents

Jirka Kosek



> I find the DocBook to HtmlHelp chain quite good; 
> however, I'd like to customize one aspect of it.
> It generates a TOC below the title page and then the TOC appears again 
> as a separate page. That is:
> [TitlePage and appended TOC ]
>      - [TOC]
>          - [Section]
>          - [Section]
>              - [Section]
>      etc

> I prefer to remove the TOC in the Title page - at least for 
> Books and Articles. For Sets I prefer it there.
> So what I would like is the following:

> [TitlePage]
>  - [TOC]    
>      - [Section]
>      - [Section]
>          - [Section]
>      etc

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>

11.

Testing for language in CHM files

David Cramer


> I'd like to base the test on the lang attribute in the 
> document, i.e <book
> lang="ja">. How would my test look like if I do that?

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>