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>

To learn how we want each piece of DocBook converted to XSL-FO, Saxon also loads the transformation stylesheets. The default DocBook stylesheets are downloaded by the build, and our own customisations are in src/docs/xsl.

This first stage, the DocBook -> XSL-FO transformation, is executed by the docbookFo build target. If you give a “gradlew docbookPdf...” command, the docbookFo 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 build/pdf-baseName tree. Stylesheets don't enter into this, nor does the original DocBook source.

This stage is represented by the docbookPdf build target.

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)