Procedure 2.1. To install the package on Windows
Note
The examples in this procedure assume a Windows installation, but the process is the same in other environments, mutatis mutandis.
If necessary, install Java 1.6 or higher.
Confirm that Java is installed and in your
PATH
by typing the following at a command prompt:java -version
Note
To build the indexer, you must have the JDK.
If necessary, install Apache Ant 1.6.5 or higher.
Unzip the Ant binary distribution to a convenient location on your system. For example:
c:\Program Files
.Set the environment variable
ANT_HOME
to the top-level Ant directory. For example:c:\Program Files\apache-ant-1.7.1
.Tip
See How To Manage Environment Variables in Windows XP for information on setting environment variables.
Add the Ant
bin
directory to yourPATH
. For example:c:\Program Files\apache-ant-1.7.1\bin
Confirm that Ant is installed by typing the following at a command prompt:
ant -version
Note
If you see a message about the file
tools.jar
being missing, you can safely ignore it.
Download Saxon 6.5.x and unzip the distribution to a convenient location on your file system. You will use the path to
saxon.jar
in Step 4 below.Note
The
build.xml
has only been tested with Saxon 6.5, though it could be adapted to work with other XSLT processors. However, when you generate output, the Saxon jar must not be in yourCLASSPATH
.In a text editor, edit the
build.properties
file in the webhelp directory and make the changes indicated by the comments:# The path (relative to the build.xml file) to your input document. # To use your own input document, create a build.xml file of your own # and import this build.xml. input-xml=docsrc/readme.xml # The directory in which to put the output files. # This directory is created if it does not exist. output-dir=docs # If you are using a customization layer that imports webhelp.xsl, use # this property to point to it. stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl # If your document has image directories that need to be copied # to the output directory, you can list patterns here. # See the Ant documentation for fileset for documentation # on patterns. #input-images-dirs=images/**,figures/**,graphics/** # By default, the ant script assumes your images are stored # in the same directory as the input-xml. If you store your # image directories in another directory, specify it here. # and uncomment this line. #input-images-basedir=/path/to/image/location # Modify this so that it points to your copy of the Saxon 6.5 jar. xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar # For non-ns version only, this validates the document # against a dtd. validate-against-dtd=true # Set this to false if you don't need a search tab. webhelp.include.search.tab=true # indexer-language is used to tell the search indexer which language # the docbook is written. This will be used to identify the correct # stemmer, and punctuations that differs from language to language. # see the documentation for details. en=English, fr=French, de=German, # zh=Chinese, ja=Japanese etc. webhelp.indexer.language=en
Test the package by running the command
ant webhelp -Doutput-dir=test-ouput
at the command line in the webhelp directory. It should generate a copy of this documentation in thedoc
directory. Typestart test-output\index.html
to open the output in a browser. Once you have confirmed that the process worked, you can delete thetest-output
directory.Important
The Saxon 6.5 jar should not be in your
CLASSPATH
when you generate the webhelp output. If you have any problems, try running ant with an emptyCLASSPATH
.To process your own document, simply refer to this package from another
build.xml
in arbitrary location on your system:Create a new
build.xml
file that defines the name of your source file, the desired output directory, and imports thebuild.xml
from this package. For example:<project> <property name="input-xml" value="
path-to/yourfile.xml
"/> <property name="input-images-dirs" value="images/** figures/** graphics/**
"/> <property name="output-dir" value="path-to/desired-output-dir
"/> <import file="path-to/docbook-webhelp/
build.xml"/> </project>From the directory containing your newly created
build.xml
file, typeant webhelp
to build your document.Important
The Saxon 6.5 jar should not be in your
CLASSPATH
when you generate the webhelp output. If you have any problems, try running ant with an emptyCLASSPATH
.