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 your -PATH
. 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 your -CLASSPATH
.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
.