Using the package

The following sections describe how to install and use the package on Windows with the sample Ant build script. 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.

Generating webhelp output using the Ant build.xml file

To install the package

[Note] 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] 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] 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] 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] 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] 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.

Using and customizing the output

To deep link to a topic inside the help set, simply link directly to the page. This help system uses no frameset, so nothing further is necessary.

[Tip] Tip

See Chunking into multiple HTML files in Bob Stayton's DocBook XSL: The Complete Guide for information on controlling output file names and which files are chunked in DocBook.

When you perform a search, the results can include brief summaries. These are populated in one of two ways:

  • By adding role="summary" to a para or phrase in the chapter or section.

  • By adding an abstract to the chapterinfo or sectioninfo element.

To customize the look and feel of the help, study the following css files:

  • docs/common/css/positioning.css: This handles the Positioning of DIVs in appropriate positions. For example, it causes the leftnavigation div to appear on the left, the header on top, and so on. Use this if you need to change the relative positions or need to change the width/height etc.

  • docs/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css: This is the theming part which adds colors and stuff. This is a default theme comes with jqueryui unchanged. You can get any theme based your interest from this. (Themes are on right navigation bar.) Then replace the css theme folder (theme-redmond) with it, and change the xsl to point to the new css.

  • docs/common/jquery/treeview/jquery.treeview.css: This styles the toc Tree. Generally, you don't have to edit this file.

Recommended Apache configurations

If you are serving a long document from an Apache web server, we recommend you make the following additions or changes to your httpd.conf or .htaccess file.

AddDefaultCharSet UTF-8 # 1
  
      # 480 weeks
      <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # 2
      Header set Cache-Control "max-age=290304000, public"
      </FilesMatch>
      
      # 2 DAYS
      <FilesMatch "\.(xml|txt)$">
      Header set Cache-Control "max-age=172800, public, must-revalidate"
      </FilesMatch>
      
      # 2 HOURS
      <FilesMatch "\.(html|htm)$">
      Header set Cache-Control "max-age=7200, must-revalidate"
      </FilesMatch>
      
      # compress text, html, javascript, css, xml:
      AddOutputFilterByType DEFLATE text/plain # 3
      AddOutputFilterByType DEFLATE text/html
      AddOutputFilterByType DEFLATE text/xml
      AddOutputFilterByType DEFLATE text/css
      AddOutputFilterByType DEFLATE application/xml
      AddOutputFilterByType DEFLATE application/xhtml+xml
      AddOutputFilterByType DEFLATE application/rss+xml
      AddOutputFilterByType DEFLATE application/javascript
      AddOutputFilterByType DEFLATE application/x-javascript
      
      # Or, compress certain file types by extension:
      <Files *.html> 
      SetOutputFilter DEFLATE
      </Files>
      

1

See Odd characters in HTML output in Bob Stayton's book DocBook XSL: The Complete Guide for more information about this setting.

2

These lines and those that follow cause the browser to cache various resources such as bitmaps and JavaScript files. Note that caching JavaScript files could cause your users to have stale search indexes if you update your document since the search index is stored in JavaScript files.

3

These lines cause the the server to compress html, css, and JavaScript files and the brower to uncompress them to improve download performance.

Search indexing

Run ant index in the webhelp directory to index the content. Running ant webhelp will do the indexing as part of the process as well.

Here's some detailed information about invoking the indexer. The indexing process is pretty smooth, so probably you doesn't need to be concerned with following details. Webhelp Ant script does all the needed bits.

  • Following should be in the CLASSPATH.

    • webhelpindexer.jar, lucene-analyzers-3.0.0.jar, lucene-core-3.0.0.jar - These three are available in the extensions/ directory of docsbook-xsl-1.76.1, and is automatically fetched to the webhelp's Ant script. Go for a XSL snapshot if you can which contains the latest version http://docbook.sourceforge.net/snapshot/

    • xercesImpl.jar, xml-apis.jar - These two comes by default with Ant 1.8.0 or prior versions. These are available under /usr/share/java directory of Linux distributions as well. Else, you may have to download, and put them to jre/lib/endorsed.

  • The main class is com.nexwave.nquindexer.IndexerMain for the version 1.76.1+. It's com.nexwave.nquindexer.IndexerTask for the versions 1.76.0 and 1.76.1.

    • Needs two parameters as command-line arguments:

      • The folder where the files to be indexed reside

      • (Optional) language. defaults to "en". See build.properties for details

    [Note] Note

    We have changed the way we invoke the webhelp indexer from the Ant Task to indexertask to direct invocation. This seems to have remove the CLASSPATH issue some people were having.

To build the indexer, you must have installed the JDK version 1.5 or higher and set the ANT_HOME environment variable.

Adding support for other (non-CJKV) languages

To support stemming for a language, the search mechanism requires a stemmer implemented in both Java and JavaScript. The Java version is used by the indexer and the JavaScript verison is used to stem the user's input on the search form. Currently the search mechanism supports stemming for English and German. In addition, Java stemmers are included for the following languages. Therefore, to support these languages, you only need to implement the stemmer in JavaScript and add it to the template. If you do undertake this task, please consider contributing the JavaScript version back to this project and to Martin Porter's project.

  • Danish

  • Dutch

  • Finnish

  • Hungarian

  • Italian

  • Norwegian

  • Portuguese

  • Romanian

  • Russian

  • Spanish

  • Swedish

  • Turkish

Adding images

This section shows how to add images to WebHelp. For that, follow the simple procedure given.

  • Put the images in a subdirectory of your source file directory. For example docsrc/images.

  • Then refer to those images from your docbook document.

    Following image is from webhelp/docsrs/images/sample.jpg. The docbook code is shown below.

    Figure 1. Sample Image


    Example 1. Example code for adding images. Note down the relative path used

    <figure>
      <title>Sample</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/sample.jpg" format="JPG"/>
        </imageobject>
      </mediaobject>
    </figure>

  • The build.properties file controls what directories are copied over from the source tree to the output tree:

    # 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/**