Using DocBook to Generate WebHelp
by: Scott Nesbitt
© 2008 DMN Communications Ltd.
Using DocBook, you can generate documents in a number of formats from a single XML source file. The area in which DocBook is lacking is in support for the generation of online help. The standard DocBook XML stylesheet distribution comes with stylesheets for generating HTML Help and JavaHelp. While useful and flexible, both formats have limitations.
While HTML Help can be compiled and viewed in Linux and UNIX, it really is best suited for Microsoft Windows. And it's difficult to properly deploy a HTML Help system over an Intranet or the Web. JavaHelp is a cross-platform format, but it can be slow and is primarily intended for use with Java applications. You can, of course, output an RTF (Rich Text Format) document and use that as the basis of an online help system. However, you need another application to compile the RTF into a usable help file.
In January, 2003, David Cramer released an XML stylesheet that enables DocBook users to generate cross-platform, browser-based help in the popular WebHelp format.
Created by eHelp Corporation (the developers of RoboHelp, now owned by Adobe), WebHelp is a method for delivering online help or documentation in a Web browser. WebHelp is simply a set of HTML and Java files. It is a very flexible format that can be used:
A WebHelp system is basically a frames-based HTML document. The left frame contains a Java applet that functions as the table of contents/navigation for the system. The right frame contains the actual content. The image below shows a WebHelp system created using the applethelp.xsl stylesheet.
Figure 1: A WebHelp system generated from DocBook sources
The main strength of WebHelp is its portability. You can view a WebHelp system in any Java-enabled Web browser on any operating system. This means you can deliver interactive documentation over the Web or on a CD-ROM and not worry about it being unusable by the recipient.
Before you can generate a WebHelp system from your DocBook sources, you must:
Note: This article assumes that you have the base DocBook XML stylesheets installed on your computer or on a server, and that you have an XSLT processor available.
The WebHelp stylesheet is named applethelp.xsl, and is available from SourceForge. Once you have downloaded the stylesheet, copy it to the /htmlhelp subdirectory of your DocBook stylesheet installation -- for example, /usr/local/db_xsl/docbook-xsl-1.62.4/htmlhelp.
The table of contents pane for a WebHelp system contains a Java applet. Neither you nor anyone in your organization has to code the applet. You can take the necessary files from the installation directory of the Microsoft HTML Help Workshop. If you do not have the HTML Help Workshop installed on your computer, you can download it from Microsoft's HTML Help site.
The files you need are in the java sub folder of the HTML Help Workshop installation directory. Before you generate the WebHelp system, you should copy the contents of the java sub folder to your working directory.
Note: If you are creating documentation on an operating system other than Windows, you should save the contents of the java sub folder in a central repository from which the files can be easily accessed as needed for other projects.
The table of contents for your WebHelp system uses several graphics from the SourceForge repository containing the WebHelp stylesheet, as shown below:
Figure 2: The graphics in a WebHelp system contents pane. Note the contents and index tabs.
You should also download the graphic files that go with the stylesheet and save them in the root folder of your WebHelp system. As with the Java files, if you are authoring on an operating system other than Windows, you should save the graphics in a central repository from which the files can be easily accessed as needed for other projects.
The DocBook stylesheets have a number of options that control the way your output is generated. A discussion of all of the available options is beyond the scope of this article. If you want a comprehensive reference to the DocBook XML stylesheets, I recommend that you buy a copy of the excellent DocBook XSL: The Complete Guide by Bob Stayton.
When creating WebHelp (or any HTML-based documents), I frequently use the following output options:
generate.index=1 -- if you have added index entries to your DocBook source file, this option generates a hyperlinked index.
The navigation pane does not display the Index tab if you have not set this option, or if you have no index entries in your document.
You will, of course, need some content in order to generate the WebHelp system. Instructions on authoring WebHelp are beyond the scope of this article. However, here are a couple of tips to keep in mind when writing:
You generate the WebHelp system using an XSLT processor, which validates XML documents and converts them to a particular format using the specified stylesheet. Most XSLT tools are command line applications which require you to type a lengthy string of commands and options. You can save keystrokes by encapsulating the commands and options you use in a script or batch file.
There are a number of XSLT processors available. I'm most familiar with Saxon, xsltproc, and Xalan. I have used these three processors in the examples below. In each of the examples, <path> indicates the directory path to your DocBook stylesheets and your source document.
To generate a WebHelp system using the Saxon processor, type the following at the command line prompt: java net.sf.saxon.Transform /<path>/document.xml /<path>/applethelp.xsl options
To use the options discussed earlier in this article, type the following at the command line prompt:java net.sf.saxon.Transform /<path>/document.xml /<path>/applethelp.xsl generate.toc=0 html.stylesheet.type=text/css html.stylesheet=webhelp.css generate.index=1
To generate a WebHelp system using the xsltproc processor, first create a sub directory named files in the directory in which you are generating the WebHelp system. Then, type the following at the command line prompt:xsltproc options /<path>/applethelp.xsl /<path>/document.xml
First, create a sub directory named files in your working directory. If you do not do this, the conversion process will fail.
Then, to use the options discussed earlier in this article, type the following at the command line prompt:xsltproc --stringparam generate.toc 0 --stringparam html.stylesheet.type text/css --stringparam html.stylesheet webhelp.css --stringparam generate.index 1 /<path>/applethelp.xsl /<path>/document.xml
To generate a WebHelp system using the Xalan processor, type the following at the command line prompt:java org.apache.xalan.xslt.Process -in /<path>/document.xml -xsl /<path>/applethelp.xsl options
To use the options discussed earlier in this article, type the following at the command line prompt:java org.apache.xalan.xslt.Process -in /<path>/document.xml -xsl /<path>/applethelp.xsl -param generate.toc 0 -param html.stylesheet.type text/css -param html.stylesheet webhelp.css -param generate.index 1
Note: You can also use the XMLmind FO Converter to transform DocBook files to WebHelp (as well as other formats). The major advantages of this tool are that it is graphical and you can create several re-usable transformations. Using the XMLmind FO Converter saves a lot of time. Instead of opening a command prompt and typing commands or running a script, I simply click a few options. This article takes a closer look at using the XMLmind FO Converter to carry out DocBook transforms.
Your XSLT processor generates the following files:
As well, both Saxon and Xalan create a folder named files, into which the HTML files that make up the content of your WebHelp system are written.
Unless something has gone horribly wrong, your WebHelp system should display in a browser perfectly. However, it's always a good idea to run a few tests.
First, do the following after you have generated your WebHelp system:
Open the file index.html in a Java-enabled Web browser, like Mozilla or Opera (or Internet Explorer if you are working in Windows). Your WebHelp system should open, complete with navigation.
You'll notice that the system lacks a search feature. To incorporate one, you'll have to turn to a third-party search tool or one that has been developed in-house (assuming one exists).
Before you bundle the WebHelp system for distribution, you might want to clean up the individual HTML topic files -- for example, indent body elements or convert the files to valid HTML 4.01 or XHTML. The best way I've found to do this is to use the utility HTML Tidy.
The WebHelp stylesheet adds a much-needed dimension to the output produced by DocBook XML. Anyone authoring in DocBook can now create rich, portable HTML document systems -- whether a full manual or an online Help system. Thanks to the flexibility of WebHelp, you have more options for delivering your documents. And you can do it with the software already installed on your system.