# README: Web-based Help from DocBook XML
Using the package

## 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.

1. 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.

2. 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.

3. 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`.

4. 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.

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

6. 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.

7. 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 |