Charles Engelke's Blog

February 8, 2004

Producing Printed Output

Filed under: docbook — Charles Engelke @ 10:58 pm

The formats we’ve produced from DocBook so far are well-suited to
on-line documents. But sometimes we want to get printed output.
Sure, we could print the HTML version from our web browser, but
the quality of the result, and our control over things like
headers and footers, aren’t very good. We want to use DocBook
tools that will generate high-quality printed output.

Actually, we’re going to work to create Adobe Acrobat
PDF files. These kinds
of files are really faithful digital representations of printed
documents. We can view and print the files with the
free Acrobat reader
program.

Producing PDF files is,
like HTML Help files, a two step operation. That’s not because
the PDF file format is
proprietary; there are plenty of tools that can create and work
with such files. It’s because the complexities of typesetting
(which is essentially what we are trying to do) call for tools
with different capabilities than XSLT processors.

To produce a PDF file from
a DocBook file, we will first use an XSLT processor with the
fo/docbook.xsl stylesheet. This will
produce an XML file in the Formatting
Objects
dialect. Formatting objects
(FO, or XSL-FO) are ways of
specifying document layout with great precision. To get from the
FO file to a
PDF file, we have to use
a Formatting Objects Processor.
Since XSL-FO is an XML standard just like
XSLT, there are now several tools available
to work with it. We’re going to start with an open source
XSL-FO processor from the Apache group called
FOP.

Procedure 3.4. Installing Apache’s FOP.

  1. Download the latest version of Apache’s
    FOP to
    a temporary directory.

  2. Expand the ZIP file
    you just downloaded in your
    c:\Program Files\docbook
    folder. This will create a folder with a name something
    like fop-0.20.5. Rename this folder
    utils, because we’re going to put more utilities
    here later.

  3. Add the c:\Program Files\docbook\utils
    folder to your Windows path. In
    Windows 2000 or
    XP you can do that using the
    System applet in your
    Control Panel, then clicking
    on the Advanced tab, and finally the
    Environment Variables button. Look
    for the system variable named Path,
    double-click it to open an edit box, and add
    ;c:\Program Files\docbook\utils at
    the very end.

We now have the PDF
publishing environment set up. Open a new command prompt (so that
it will have the updated Path you just
entered), change to the folder containing your DocBook file, and
convert it file to an XSL-FO file, and then to
a PDF file:

java -jar "c:\Program Files\docbook\saxon\saxon.jar" \
-o sample1.fo sample1.docbook \
"c:\Program Files\docbook\xsl\fo\docbook.xsl"

to create the XSL-FO file, and then:

fop sample1.fo sample1.pdf

to convert formatting objects to PDF.
You will probably see a lot of error, warning, and informational
messages on the screen; Apache’s FOP
doesn’t yet handle all possible XSL-FO
constructs, hence the messages. You should still get a good
output file, though.

The resulting PDF file
can be run from the command line with

start sample1.pdf

or from Windows Explorer just by double-clicking.

We’ve now produced a variety of different output formats from a
single DocBook source file, and have installed and used several
different DocBook tools. Next time we’re going to clean up
our development environment and write some batch files to make
these steps a lot easier.

Advertisements

Create a free website or blog at WordPress.com.

%d bloggers like this: