Generating webhelp output using the Ant build.xml file - - README: Web-based Help from DocBook XML

Generating webhelp output using the Ant build.xml + file

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.
1. 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.
1. Unzip the Ant binary distribution to a convenient location on your system. For + example: c:\Program Files.
2. 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.
3. Add the Ant bin directory to your PATH. For + example: c:\Program Files\apache-ant-1.8.0\bin
4. 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=0

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 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:
1. 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>
```
2. From the directory containing your newly created build.xml + file, type ant webhelp to build your document.

Prev	Up	Next
	Home

README: Web-based Help from DocBook XMLUsing the package