How the PDF is created

To better understand the effects of the steps you're going to take, here's a brief overview of how your DocBook source is converted to a PDF file.

First stage: DocBook -> XSL-FO

A so-called XSL transformer by the name of Saxon reads the DocBook XML source, converts it to XSL-FO format, and saves it in the manual/inter/fo tree. The FO in XSL-FO stands for Formatting Objects. Like DocBook, this is an XML format, but presentation-oriented. Below is a typical chunk of XSL-FO:

<fo:block keep-together="always" margin-left="0pc"
          font-family="sans-serif,Symbol,ZapfDingbats">
  <fo:block font-family="sans-serif" font-weight="bold" 
            keep-with-next.within-column="always"
            space-before.minimum="0.8em" space-before.optimum="1.0em"
            space-before.maximum="1.2em" 
            color="darkblue" text-align="start">
    <fo:block font-size="19.8pt">SQL Syntax</fo:block>
  </fo:block>
</fo:block>

The Saxon tool is located in manual/lib/saxon.jar. To learn how we want each piece of DocBook converted to XSL-FO, Saxon also loads the transformation stylesheets. The default DocBook stylesheets are in manual/src/docs/docbook, and our own customizations in manual/src/docs/xsl.

This first stage, the DocBook -> XSL-FO transformation, is executed by the fo build target. If you give a “build pdf...” command, the fo target is called internally, but you can also call it explicitly to generate only the XSL-FO file and not the PDF.

Second stage: XSL-FO -> PDF

The XSL-FO file is converted to PDF by another tool, Apache FOP (Formatting Objects Processor). The result is stored in the manual/dist/pdf tree. Stylesheets don't enter into this, nor does the original DocBook source. Apache FOP lives in manual/lib/fop.jar.

This stage is represented by the fo2pdf build target. It too is called internally by the pdf target, but you can also call it yourself, for instance if you have manually edited the .fo file (which is sometimes necessary, alas).

The sections to come will guide you through the steps listed in the Introduction. This table shows where each of them affects the DocBook-to-PDF build process:

Step Description Affects

1 Finding the fonts you need (preparatory step)

2 Overriding the stylesheet fonts Stage 1: XSL-FO generation

3 Creation of metrics files Stage 2: PDF production

4 Creation of FOP userconfig file Stage 2: PDF production

5 PDF building and committing (final step – the build itself)

Step	Description	Affects
1	Finding the fonts you need	(preparatory step)
2	Overriding the stylesheet fonts	Stage 1: XSL-FO generation
3	Creation of metrics files	Stage 2: PDF production
4	Creation of FOP userconfig file	Stage 2: PDF production
5	PDF building and committing	(final step – the build itself)