MySQL Guide to MySQL Documentation  /  Building Documentation Formats  /  How Different Formats are Built

2.2 How Different Formats are Built

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

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.

  1. The ID mapping system rebuilds any outdated ID maps. ID maps are used to identify whether an ID reference in a document is internal or external and allows the build system to automatically remap links it considers to be external to current document being generated. For more information, see Section 3.2, “ID Mapping System”.

    ../tools/idmap.pl mysqldoc-guide/en formats.xml
  2. XSLT processor converts the base document into a prepared state. This builds the target document-prepped.xml. Included in this process is the entity expansion, the incorporation of the included XML files, and any custom DocBook XML formatting which is applied to all output formats.

    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
    
  3. The ID remapper is executed on the generated source. Any links that cannot be resolved internally are converted into URL links that link directly to the MySQL online HTML for the appropriate section.

    ../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
  4. At this point, we now have a single DocBook XML document that is ready to be translated into the various output formats. From here on, the exact steps followed are unique for the output format being produced.

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.