The basic process for building all documentation follows a similar sequence. You can see the sample output from building this guide into PDF format below:

../tools/idmap.pl mysqldoc-guide/en formats.xml
xsltproc --xinclude --novalid  \
--stringparam repository.revision "`../tools/get-svn-revision`" \
        --param map.remark.to.para 0 \
        --stringparam qandaset.style "" \
        ../xsl.d/dbk-prep.xsl mysqldoc-guide.xml | ../tools/bug-prep.pl > mysqldoc-guide-prepped.xml.tmp
../tools/idremap.pl  --srcpath=". " mysqldoc-guide-prepped.xml.tmp > mysqldoc-guide-prepped.xml.xprep
mv mysqldoc-guide-prepped.xml.xprep mysqldoc-guide-prepped.xml
rm -f mysqldoc-guide-prepped.xml.tmp
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)
lisitem encountered in itemizedlist, but no template matches.
mv mysqldoc-guide.fo-tmp mysqldoc-guide.fo
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; \
fi
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

Note that all XSL stylesheets, including the MySQL specific customizations, CSS and other elements are stored within the xsl.d directory. For all output formats, the custom MySQL specific XSL stylesheet is used. This enables us to specify the custom setup and structure of the particular format. Each of the custom stylesheets then imports the default DocBook XSL stylesheet set.

Let's look at the steps in more detail. The relevant code is provided so that you can identify the individual steps.

There are a number of advantages to creating the intermediate prepped XML document. The first is that because the prepped file is used by all the output format targets, we ensure that all the different forms of the documentation use the same source. If there is a change in one of the source files, the prepped version of the file has to be rebuilt, and then all the output formats need to be rebuilt too. It is impossible for the PDF and HTML versions of a document to differ in their content.

The second advantage is that because the prepped file is created before the output formats are generated, we reduce the overall time to produce a particular document in a particular format. Instead of restarting the entire process for each document, we only have to run the final transformation step for each target output format.

Although the aim is to create the full documents using this system, the same targets and systems can also be used to create a document from any sourcefile. This is very useful if you want to test the edits or corrections in one of the individual chapters or sections.