diff options
Diffstat (limited to 'src/documentation/content/xdocs/DnI/README')
| -rw-r--r-- | src/documentation/content/xdocs/DnI/README | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/DnI/README b/src/documentation/content/xdocs/DnI/README new file mode 100644 index 000000000..9138da809 --- /dev/null +++ b/src/documentation/content/xdocs/DnI/README @@ -0,0 +1,77 @@ +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 book.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://cvs.sourceforge.net/viewcvs.py/*checkout*/docbook/xsl/'. I am +not quite sure if the latter URL is correct. 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 learn from it how +the BookMaker class can be called. If you use the Makefile, you must +edit the class paths to reflect your java setup. Set the environment +variable PROGOPTS=--useCatalog if you want to use a catalog. I have +better results with Xerces and the catalog resolver; therefore Xerces +is placed before Saxon in the class paths. + +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 \ + book.xml cust-xhtml-docbook.xsl + +java $JAVAFLAGS -cp "$SAXONCLASSPATH:$CLASSPATH" \ + com.icl.saxon.StyleSheet \ + -o ../documentation-html/book.html \ + book.xml cust-html-docbook.xsl + +java $JAVAFLAGS \ + -cp $SAXONCLASSPATH:$FOPCLASSPATH:$AVALONCLASSPATH:$CLASSPATH \ + org.apache.fop.apps.Fop \ + -xml book.xml -xsl cust-html-docbook.xsl -pdf book.pdf + +I will try to construct an ant build file and an XML catalog which +make conversion with your own XML and Java system easier. + +$Id$ |