Charles Engelke's Blog

We finished up writing the DocBook files with a pointer to
DocBook: The
Definitive Guide. The whole book is available on-line.

Now we get to generating output from the DocBook files we’ve created.
First, with DSSSL stylesheets. These are written in Scheme, a dialect of
Lisp, and are falling behind the XSL stylesheets (though this is the only
option if you use SGML instead of XML for DocBook). To use DSSSL to
generate output, use Jade or OpenJade to create TeX, RTF, or SGML (which can
create HTML, too). You also need the SP or OpenSP parser. For the TeX
tools (which produces gorgeous print) you also need a bunch of TeX tools (I
like miktex for Windows, though
cygwin, a set of Unix tools under Windows,
has a good TeX in it, too.

Example commands. To get print from an SGML file, follow these steps:

openjade -d print/docbook.dsl -t tex -V tex-backend myfile.sgml

pdfjadetex myfile.tex (to go straight to PDF)

jadetex myfile.tex
dvips -o myfile.ps myfile.dvi (to go to PostScript)

For the TeX commands you have to run them three times each! (That’s no
surprise to us old TeX hands; TeX is a single pass processor, so sometimes
the first pass saves information needed for the next pass, and so on.)

If you use XML (like I do), you replace the first command with

openjade -d print/docbook.dsl -t tex -V tex-backend xml.dcl myfile.xml

I’m going to try these out the first chance I get, and I’ll note the results
here.

We can use XSL instead of DSSSL, so long as we use XML DocBook files (and
that’s all I’m ever likely to use). Get the standard stylesheets from
docbook.sourceforge.net. The main stylesheet is html/docbook.xsl to
get a single HTML file out, html/chunk.xsl to get lots of small HTML files,
and fo/docbook.xsl to get FO output for later printing. Once you’ve saved
the stylesheets on your PC (say, in c:\xslt) you process them with any XSLT
processor. For example, to use xsltproc:

xstlproc --output myfile.html c:\xslt\html\docbook.xsl myfile.xml

for HTML output, or

xstlproc --output myfile.fo c:\xslt\fo\docbook.xsl myfile.xml

In Saxon on Unix, you’d use this for HTML output:

java -cp "/usr/java/saxon.jar:/docbook-xsl/extensions/saxon65.jar" \
com.icl.saxon.StyleSheet -o myfile.html myfile.xml \
/usr/share/docbook/html/docbook.xsl

I have to figure out all the right paths for Saxon under Windows.

Once your stylesheet transformation has produced FOP, get PDF as follows.
First, on Unix(y) systems:

fop.sh -fo myfile.fo -pdf myfile.pdf

On Windows, use:

fop.bat -fo myfile.fo -pdf myfile.pdf

To convert straight from XML source on Unix:

fop.sh -xsl /docbook-xsl/fo/docbook.xsl -xml myfile.xml -pdf myfile.pdf

These addresses can be simplified using an XML catalog. The presenter has
more information on
his website.

You can reference parameters in the stylesheet and pass values on the
command line when you process the XML file. This should help automation
without having to have a lot of nearly identical stylesheets. A good way to
create your custom stylesheets is to write a new stylesheet, pull in the
standard one, then add your own templates. For example:

<?xml version="1.0">
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="html/docbook.xsl"/>
...your parameters and templates here...
</xsl:stylesheet>

You can also use XML locale files (e.g., common/en.xml) to help
generate output in different languages (the common words like “Chapter”).

Our presenter, Bob Stayton, has written a
book on all this.
The HTML version is free to browse, but we’d have to buy the PDF. I’m going
to look into this, because I think it’s likely to be an extremely valuable
reference. This tutorial has certainly been great.

I feel pretty good about my ability to go do useful stuff with DocBook
now. I’m going to download the various tools and try them out. I’ll post
my examples and results when I do this.