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:

http://www.onjava.com/pub/a/onjava/2003/10/15/javahelp_docbook.html

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:

/local/wecn/apps/docbook-xsl-1.68.1/javahelp/javahelp.xsl

The other file is used to create PDF:

/local/wecn/apps/docbook-xsl-1.68.1/fo/docbook.xsl

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:

/local/wecn-web/we-web/xml/html/wecn.css

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:

/local/wecn/apps/saxon6_5_3/

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

4.3. FOP

FOP is located in the following directory:

/local/wecn/apps/fop-0.20.5/

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.

Note

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:

/local/wecn/apps/jh2.0

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

Note

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
DOCBOOK_XSL_HOME=/local/wecn/apps/docbook-xsl-1.68.1
JAVAHELP_HOME=/local/wecn/apps/jh2.0
CLASSPATH=${JAVAHELP_HOME}/javahelp/lib/jhall.jar:/local/wecn/apps/saxon6_5_3/saxon.jar:/local/wecn/apps/fop-0.20.5/build/fop.jar:/local/wecn/apps/fop-0.20.5/lib/batik.jar:/local/wecn/apps/fop-0.20.5/lib/xalan-2.4.1.jar:/local/wecn/apps/fop-0.20.5/lib/xercesImpl-2.2.1.jar:/local/wecn/apps/fop-0.20.5/lib/avalon-framework-cvs-20020806.jar
# Location of html output
HTML_DIR=/local/wecn-web/we-web/xml/html
#HTML_DIR=/home/wecn05/mpcrosso/make_test/html
# Location of sources
XML_DIR=/local/wecn-web/we-web/xml/sources
#XML_DIR=/home/wecn05/mpcrosso/make_test/sources
DOC_HOME=/local/wecn-web/we-web/xml

# Executable paths
FOP=/local/wecn/apps/fop-0.20.5/fop.sh

all: convert2html index reset notice

# Create a PDF of the information
pdf: 
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)
convert2html:
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
index:
${JAVAHELP_HOME}/javahelp/bin/jhindexer ${HTML_DIR}

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

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

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

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

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