olink.docbook-xsl.webhelp.docs.ch02s01.html Maven / Gradle / Ivy
Generating webhelp output using the Ant build.xml file - - README: Web-based Help from DocBook XML 
README: Web-based Help from DocBook XML
Using the package
Procedure 1. To install the package
Note
The examples in this procedure assume a Windows
installation, but the process is the same in other
environments, mutatis
mutandis. In an environment where unix
shell command are available, you can also use the
Makefile.sample as a starting point
for creating your build script. To use
Makefile.sample you must have
xsltproc and java
available in your PATH. You can also use
the Docbkx Maven plugin to generate webhelp.
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.8.0 or higher. See Ant installation instructions.
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.8.0.
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.8.0\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 5 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.
Download Xerces2
Java and extract it to a convenient location on
your file system. You will need the
xercesImpl.jar and
xml-apis.jar from this distribution
in in Step 5.
In a text editor, edit the
build.properties file in the
webhelp directory and make the changes indicated by the comments.
Important
You must set appropriate values for
xslt-processor-classpath,
xercesImpl.jar, and
xml-apis.jar.
See the DocBook reference
documentation for detailed information about the
available webhelp and other parameters. Note that not all
DocBook parameters are passed in to the xsls by the
build.xml by default. You may need
to modify the build.xml to pass in
some DocBook
parameters.
# 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 the follosing so that they point to your local
# copy of the jars indicated:
# * Saxon 6.5 jar
# * Xerces 2: xercesImpl.jar
# * xml-commons: xml-apis.jar
xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
xercesImpl.jar=/usr/share/java/xercesImpl.jar
xml-apis.jar=/usr/share/java/xml-apis.jar
# For non-ns version only, this validates the document
# against a dtd.
validate-against-dtd=true
# The extension for files to be indexed (html/htm/xhtml etc.)
html.extension=html
# 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
# Enables/Disables stemming
# Stemming allows better querying for the search
enable.stemming=true
# Set admon.graphics to 1 to user graphics for note, tip, etc.
admon.graphics=0
suppress.footer.navigation=0Test 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 the doc directory. Type start
test-output\index.html to open the output in a
browser. Once you have confirmed that the process worked,
you can delete the test-output directory.
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 the
build.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, type ant webhelp to build your document.
