2.2.4 How PDFs are Produced

You cannot convert DocBook XML into PDF directly. The reason for this is that the DocBook XML standard is designed to be device independent (that is, they don't rely on fixed page or view sizes). The HTML format is also device independent, hence why the XSL stylesheet can be used to convert the source to HTML directly.

For PDF the DocBook XML is first translated into the Formatting Objects (FO) format. The FO format enables you to specify output attributes, such as the page size, and handles the flow and formatting of the source text and illustrations.

The FO file can then be converted using Apache's FOP system into the PDF format. The resulting sequence is therefore:

  1. Transform the prepared XML file into an FO format file, specifying the target page size, margins and other elements (through the XSL stylesheet). The process also applies any specialized markup for the FO or PDF format.

    xsltproc --xinclude --novalid  \
                --output - ../xsl.d/strip-remarks.xsl mysqldoc-guide-prepped.xml \
                | xsltproc --xinclude --novalid  \
                --stringparam l10n.gentext.default.language en \
                --output mysqldoc-guide.fo-tmp ../xsl.d/mysql-fo.xsl -
                Making portrait pages on USletter paper (8.5inx11in)
                mv mysqldoc-guide.fo-tmp mysqldoc-guide.fo
  2. Transform the FO file into the PDF file. To ensure that any multibyte characters (such as those in the Chinese/Japanese/Korean FAQ in the reference manual) are rendered correctly, we parse the generated FO and change the font specification for these elements. This step is only followed if the userconfig.xml file, which is required by FOP and defines fonts, is available. If the file is not available, we still transform the file into PDF.

    if [ -f ../xsl.d/userconfig.xml ]; then \
         ../tools/fixup-multibyte.pl mysqldoc-guide.fo > mysqldoc-guide.fo.multibyte; \
         mv mysqldoc-guide.fo.multibyte mysqldoc-guide.fo; \
         fop -q -c ../xsl.d/userconfig.xml mysqldoc-guide.fo mysqldoc-guide.pdf-tmp > mysqldoc-guide.pdf-err; \
    else \
         fop -q mysqldoc-guide.fo mysqldoc-guide.pdf-tmp > mysqldoc-guide.pdf-err; \
    mv mysqldoc-guide.pdf-tmp mysqldoc-guide.pdf
    sed -e '/hyphenation/d' < mysqldoc-guide.pdf-err
    [ERROR] Unknown enumerated value for property 'span': inherit
    [ERROR] Error in span property value 'inherit': org.apache.fop.fo.expr.PropertyException: No conversion defined
    rm -f mysqldoc-guide.pdf-err

The current documentation tree includes standard FO (and therefore PDF) output definitions for A4, Letter and 6in x 9in (standard book) sized output.