The first steps with DocBook

Create a document

Open a new XML document by typing C-x C-f ~/dbtest.xml. Insert the DocBook document type declaration via the DTD->Insert DTD->DocBook XML 4.1.2 menu command. Insert some elements into the document, e.g. starting with the chapter and sect1 tags. Enter some para elements to hold some text. Validate your document with the SGMLValidate menu command. Make sure you use the SGML declaration for XML documents (xml.dcl).

Create HTML output

HTML output is the simpler transformation as it requires only one application (the XSLT engine). Here is how you can generate a HTML file from your test document with the various XSLT engines (the backslashes at the end of the lines denote continuation of the line - don't type them in):

~# xsltproc /usr/local/lib/xml/stylesheets/docbook-xsl/html/docbook.xsl \
dbtest.xml > dbtestxp.html
~# java -cp "C:\Programs\java\xt.jar;C:\Programs\java\xp.jar" \
com.jclark.xsl.sax.Driver dbtest.xml \
"C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\html\docbook.xsl" \
> dbtestxt.html
~# java -cp "C:\Programs\java\xalan.jar;C:\Programs\java\xerces.jar" \
org.apache.xalan.xslt.Process -in dbtest.xml \
-xsl "C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\html\docbook.xsl" \
-out dbtestxc.html
~# java -cp "C:\Programs\java\saxon.jar" com.icl.saxon.StyleSheet \
-o dbtestsx.html dbtest.xml \
"C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\html\docbook.xsl"

Create printable output

Creating printable output from an XML document is a two-step procedure in most cases: First we have to create an intermediate XML file containing formatting objects (the FO file). This is done with an XSLT processor and a suitable stylesheet. The second step needs some sort of formatting objects processor to actually create the printable output from the intermediate FO file. Let's first see how we can create this FO file with our XSLT engines (you should of course only run those engines that you actually installed). In case you want to try all of them it is prudent to use different names for the output files each time, as shown here (the backslashes at the end of the lines denote continuation of the line - don't type them in):

~# xsltproc /usr/local/lib/xml/stylesheets/docbook-xsl/fo/docbook.xsl \
dbtest.xml > dbtestxp.fo
~# java -cp "C:\Programs\java\xt.jar;C:\Programs\java\xp.jar" \
com.jclark.xsl.sax.Driver dbtest.xml \
"C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\fo\docbook.xsl" \
> dbtestxt.fo
~# java -cp "C:\Programs\java\xalan.jar;C:\Programs\java\xerces.jar" \
org.apache.xalan.xslt.Process -in dbtest.xml \
-xsl "C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\fo\docbook.xsl" \
-out dbtestxc.fo
~# java -cp "C:\Programs\java\saxon.jar" \
com.icl.saxon.StyleSheet -o dbtestsx.fo dbtest.xml \
"C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl\fo\docbook.xsl"

Now we try to turn our FO file into a PDF file using the PassiveTeX macros. Run the following command, substituting the FO filename as appropriate:

~# pdfxmltex dbtest.fo

Alternatively we can use FOP to transform the XML document to PDF with a single command (this is the exception to the two-step rule, but you can guess from the classpath that FOP uses Xalan internally):

~# java -cp "C:\Programs\java\fop.jar;C:\Programs\java\batik.jar; \
C:\Programs\java\jimi-1.0.jar;C:\Programs\java\xalan.jar; \
C:\Programs\java\xerces.jar;C:\Programs\java\logkit-1.0b4.jar; \
C:\Programs\java\avalon-framework-4.0.jar" org.apache.fop.apps.Fop -xsl \
"C:\cygwin\usr\local\lib\xml\stylesheets\docbook-xsl-1.45\fo\docbook.xsl" \
-xml test.xml -pdf test.pdf

Finally we can try and see what the RTF output from the FO file looks like (substitute the FO filename as appropriate):

~# java -cp "C:\Programs\java\jfor-0.5.1.jar;C:\Programs\java\xerces.jar" \
ch.codeconsult.jfor.main.CmdLineConverter dbtest.fo dbtest.rtf

Use the helper script to simplify the transformations

Stressed out by the endless command lines? The dbxml script simplifies the above mentioned transformations. Before attempting to run the script you should edit the user-customizable section at the top of the file to adjust a few paths and default settings.

Synopsis

dbxml [-d stylesheet] [-h] [-p processor] [-t outformat] {docbook-xml-file...}

Description

This script transforms a DocBook XML document and creates either HTML, RTF, or PDF output. The output files will be automatically named after the basename of the input file.

The -d option allows to choose between several stylesheets. This may e.g. be a new driver file for the DocBook stylesheets. In order to use this option you have to add your driver files to the script (see the comments in the code).

dbxml -h displays a short usage screen and exits.

Specify the XSLT engine with the -p option. Use either xalan, xt, saxon, or xsltproc.

Use the -t option to specify the output format. Possible values are html, rtf, and pdf.

Examples

~# dbxml -p xsltproc -t pdf dbtest.xml
~# dbxml -p xalan -t html dbtest.xml

The first command uses xsltproc to generate PDF output from the input file dbtest.xml. The second command uses Xalan to create HTML output from the same input file.