4. The JavaHelp, HTML and PDF Output Tool Chain

One of the advantages of DocBook is there are several toolchain options that allow you to transform XML documents into several different types of output. WECN documentation can currently be transformed into JavaHelp, HTML and PDF output using the following tools:

The process that is used to create documentation output closely follows a tutorial that is available online at ONJava.com:


4.1. DocBook XSL

Two XSL files are used to create output. One is used to create the HTML that is used by JavaHelp. This file is located in the following directory:


The other file is used to create PDF:


These XSL files can be modified to customize the output. One file ( javahelp.xsl ) has been modified slightly in order to apply a stylesheet to every HTML file that is generated. The following line was added to make this happen:

<xsl:param name="html.stylesheet" select="'wecn.css'"/>

This style sheet is in the same directory as the output HTML:


This file can also be modified to change the appearance of the output HTML.

More information on DocBook XSL is available on http://www.sagehill.net/docbookxsl/.

4.2. Saxon

Saxon is located in the following directory:


More information about FOP is available on http://saxon.sourceforge.net/

4.3. FOP

FOP is located in the following directory:


More information about FOP is available on http://xml.apache.org/fop/.

4.4. JavaHelp

JavaHelp is just a interface the displays HTML files in a manner that allows you to browse through them in a collapsible tree structure. It also provides direct links to pre-defined book marks and full-text search capabilities.


By default there are some words that can't be searched like "the" so it doesn't crash your computer when as it generates a million billion hits.

JavaHelp is located in the following directory:


More information about JavaHelp is available on http://java.sun.com/products/javahelp/index.jsp.

4.5. Creating Output

The following procedure is used to create HTML and JavaHelp Output

  1. Open a terminal.

  2. Navigate to /local/wecn-web/we-web/xml/html.

  3. Run make at the command line

  4. Run make verify to open a local copy of the documentation viewer to verify that your new section, category or book has been created properly


There is currently a bug in the JavaHelp indexing function. If the full text search functionality doesn't work, run make again. Part of this problem will probably be solved by upgrading to the latest version of Java.

The following procedure is used to create PDF Output

  1. Open a terminal

  2. Navigate to /local/wecn-web/we-web/xml/.

  3. Run make pdf at the command line.

The following make file is what is used to create output from the DocBook XML files:

# Michael Crosson
# Makefile for creation of html from docbook files stored in
# /local/wecn-web/we-web/xml

# "Environment" variables
# Location of html output
# Location of sources

# Executable paths

all: convert2html index reset notice

# Create a PDF of the information
java -Xmx128m -cp ${CLASSPATH} org.apache.fop.apps.Fop -xml ${XML_DIR}/wecn.xml -xsl /local/wecn/apps/docbook-xsl-1.68.1/fo/docbook.xsl -pdf ${DOC_HOME}/documentation.pdf

# Convert book to HTML (dumps to CURRENT DIR)
java -cp ${CLASSPATH} com.icl.saxon.StyleSheet ${XML_DIR}/wecn.xml ${DOCBOOK_XSL_HOME}/javahelp/javahelp.xsl

# Index the HTML generated
#${JAVAHELP_HOME}/jhindexer $H
${JAVAHELP_HOME}/javahelp/bin/jhindexer ${HTML_DIR}

# Check to make sure its all converted properly
java -cp ${CLASSPATH} -jar ${JAVAHELP_HOME}/demos/bin/hsviewer.jar -helpset ${HTML_DIR}/jhelpset.hs

# Print out the way to do a verify
echo Run "make verify" to check to make sure the output is correct

# Remove all html files that have been previously generated
rm ch*.html
rm index.html

# Run the demo of javahelp
java -jar ${JAVAHELP_HOME}/demos/bin/UserGuide.jar

#Reset permissions on the HTML files
chmod 775 ${HTML_DIR}/*
chgrp wesupport ${HTML_DIR}/*