OpenZz Documentation Source README

This README describes how to build the help files.  Pre-built help files are distributed with Zz - If you want help on Zz itself consult those manuals in the "doc" directory.

The reference manual/help documentation is autogenerated from the xml sources in this directory to the output formats (html, ps, pdf) by the generation schemes described below.  These xml sources follow the "DocBook" DTD syntax described at the following sites:

  http://docbook.org/
  http://www.oasis-open.org/docbook/
  http://nwalsh.com/docbook/

To ensure that any further work on these sources encounters the same level of success that we are achieving so far, we have placed the versions of the tools(tarballs) that we used on the OpenZz project website at:

  http://openzz.sourceforge.net/src/

It is of course best to use the latest versions but should a future incomparability arise, the versions we used are there.  The DocBook DTD Manual is available online at:

  http://www.oasis-open.org/docbook/documentation/reference/index.shtml 

Below are the steps used to generate each of the output formats from the sources.

TO get an idea of what these steps provide at a high level, view the friendly
diagram at:
   http://nwalsh.com/docbook/procdiagram/index.html

*******************
* GENERATING HTML *
*******************

The xml sources are converted to html output by means of processing them with
xsl stylesheets.  To produce the output do the following:

1) Make sure you have the following 4 items:
 1.a) A Java runtime
 1.b) An xsl processing engine - we used Xalan from Apache.org, 
      but instead of getting just the Xalan distribution we used the Xalan XSLT
      engine that comes with the FOP tool used in the steps below for generating
      other outputs (ps,pdf...)

      http://xml.apache.org/dist/fop/

      Make sure the xalan.jar and xerces.jar jars are in your classpath:
       CLASSPATH=<fop_path>/lib/xalan-2.0.0.jar:<fop_path>/lib/xerces-1.2.3.jar
 1.c) The DocBook DTD - either download the latest from

        http://www.oasis-open.org/docbook/xml/4.1.2/index.shtml

      or use the version we used from our project directory on the SourceForge
      site.  See step 2 about location.
 1.d) The xsl stylsheets.  Dowload the xsl/html bundle from 
      http://sourceforge.net/projects/docbook
      or from our project directory.
2) The zzdoc.xml file contains a reference to the DocBook DTD with a relative
   file path - you'll need to do one of the following:
   - Expand the DocBook DTD inside this doc/src directory (the relative path
     "docbook-dtd/docbookx.dtd" will work)
   - Make a symbolic link to get the same result
   - Edit zzdoc.xml to point to the correct location
   Things may be easier for you if you do this same kind of installation or
   directory aliasing for the stylesheets in step 1d.
3) With Java installed and the xsl engine(ie. Xalan) jars in your classpath you
   should be able to generate the output by using something simillar to the
   following command:

$ java org.apache.xalan.xslt.Process -IN zzdoc.xml -XSL <path>/docbook.xsl -OUT ../zzdoc.html

You will have the replace <path> to point accurately to your docbook.xsl file
 (from the DocBook xsl/html bundle).

Note: the html output may expect a subdirectory "images" containing graphics from the like-named docbook xsl directory.  Link or copy it into place as needed.

Currently it takes 35 seconds on our server for this generation process to run.


*****************************************************************
* GENERATING PDF, PCL, PS, SVG, XML (area tree representation), * 
*            Print, AWT, MIF and TXT                            *
*****************************************************************

For generating all other formats besides html we use the Xsl:FO (Xsl Formatted
Objects) processor "FOP".  Before performing any conversions download and expand
FOP from our source directory or from:

  http://xml.apache.org/dist/fop/

1) Make sure FOP is installed
2) Process your xml files using the "docbook.xsl" template in the "/fo"
   subdirectory of the docbook

$ java org.apache.xalan.xslt.Process -IN zzdoc.xml -XSL <path>/fo/docbook.xsl -OUT <path>/zzdoc.fo

3) Process the output of step 2 using "fop".