src/documentation/content/xdocs/DnI/README

Readme for `FOP's design and implementation'

This directory contains the documentation entitled `FOP's design and
implementation'.

The book is structured according to the Docbook XML DTD version 4.2,
top-level element book.

The top level file is DnI.xml. It calls in the various chapter files.

The book can be converted to XHTML, HTML and FO using the Docbook XSL
stylesheets. For each of these formats there are customization XSL
stylesheets, which should be called as the main stylesheet of the
conversion. The customization stylesheets were written against version
1.64.1. The customization for FO is rather heavy, and may prove
incompatible with later versions of the docbook stylesheets. Of
course, you can always convert without the customization or with your
own customization. The changes will only affect the layout, not the
content of the book.

The customization stylesheets for XHTML and HTML use the ability of
the docbook stylesheets to write the resulting files in chunks. It
makes sense to send the conversion result into a separate
directory. If you make both conversions, you must send them to
different directories, as they produce files of the same name. You can
produce the result in a single file by making a small change at the
top of the customization stylesheets: import the stylesheet
docbook.xsl instead of chunk.xsl.

For the XHTML and HTML conversions I have obtained the best conversion
results using Saxon. I have used FOP-0.20.5 for FO Processor.

The top-level file assumes that the docbook DTD files are located in
`http://www.oasis-open.org/docbook/xml/4.2/'. The customization
stylesheets assume that the docbook stylesheets are located in
`http://docbook.sourceforge.net/release/xsl/current/'. If you want to
use local files from your XML installation, you must change these
paths at the top of the top-level XML file and of each customization
stylesheet.  Alternatively, you can use catalog entries to map the
Public ID for the Docbook DTD and the system id of the docbook XSL
stylesheets to your local paths.

You can use the included java class BookMaker to generate the various
forms of the documentation. Note that it requires the Jakarta Commons
CLI package. Call BookMaker with the option '--help' to get a short
overview of its usage. Use the included Makefile or Ant build file, or
learn from them how the BookMaker class can be called.

Unfortunately, I do not know of a standard file system setup for java
jar files. The class paths in the Makefile reflect the java setup of a
Debian Sarge system. Moreover, it allows for the same setup in
/usr/local, for jar files installed locally. If you use the Makefile,
you must edit the class paths to reflect your own java setup. If you
want to use a catalog with the Makefile, you should set the
environment variable PROGOPTS=--useCatalog. I have better results
with Xerces and the catalog resolver; therefore Xerces is placed
before Saxon in the class paths.

For instructions to use the Ant build file, see the comments at the
top of that file.

If you do not use a catalog, you can also use Saxon and FOP from the
command line. The following are typical invocations. Here the
classpaths have obvious meanings. JAVAFLAGS are any other options for
java, possibly none.

java $JAVAFLAGS -cp "$SAXONCLASSPATH:$CLASSPATH" \
	com.icl.saxon.StyleSheet \
	-o ../documentation-xhtml/book-xhtml.xml \
	DnI.xml cust-xhtml-docbook.xsl

java $JAVAFLAGS -cp "$SAXONCLASSPATH:$CLASSPATH" \
	com.icl.saxon.StyleSheet \
	-o ../documentation-html/book.html \
	DnI.xml cust-html-docbook.xsl

java $JAVAFLAGS \
	-cp $SAXONCLASSPATH:$FOPCLASSPATH:$AVALONCLASSPATH:$CLASSPATH \
	org.apache.fop.apps.Fop \
	-xml DnI.xml -xsl cust-html-docbook.xsl -pdf book.pdf

$Id$