Using DocBook toolchain

Table of Contents

Converting DocBook to other file formats

a2x Toolchain Wrapper
AsciiDoc DocBook XSL Drivers

Converting DocBook to other file formats

DocBook files are validated, parsed and translated by a combination of applications collectively called a DocBook tool chain. The function of a tool chain is to read the DocBook markup (produced by AsciiDoc) and transform it to a presentation format (for example HTML, PDF, HTML Help).

A wide range of user output format requirements coupled with a choice of available tools and stylesheets results in many valid tool chain combinations.

The DocBook toolchain currently used for processing AsciiDoc documentation is xsltproc(1), FOP and DocBook XSL Stylesheets. These tools are freely available for Linux and Windows systems.

Why Generate HTML via DocBook?

AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route:

HTML from DocBook includes automatically generated indexes, tables of contents, footnotes, lists of figures and tables.
DocBook toolchains can also (optionally) generate separate (chunked) linked HTML pages for each document section.
Toolchain processing performs link and document validity checks.

On the other hand, HTML output directly from AsciiDoc is still very useful in the following situations:

Generating Websites.
Generating HTML documents that don't require front and back matter.
Where there is no suitable DocBook toolchain.

If you require indexes, tables of contents or output formats other than HTML you would feed AsciiDoc's DocBook output to a DocBook toolchain. The distributed AsciiDoc User Guide plus the article and book example documents have been generated in this way.

The toolchain processing steps are:

Convert AsciiDoc (*.txt) documents to DocBook XML (*.xml) using AsciiDoc.
Convert DocBook XML documents to HTML, XSL-FO or HTML Help files using DocBook XSL Stylesheets and the xsltproc(1) XML parser.
Convert the XSL-FO (*.fo) files to PDF using FOP and HTML Help source (*.hhp) files to HTML Help (*.chm) files using the Microsoft HTML Help Compiler.


	These steps can be automated by using the AsciiDoc a2x(1) toolchain wrapper command.

a2x Toolchain Wrapper

One of the biggest hurdles for new users seems to be using a DocBook XML toolchain. a2x(1) can help — it's toolchain wrapper command that will generate XHTML (chunked and unchunked), PDF, man page, HTML Help and text file outputs from an AsciiDoc text file. a2x(1) does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. a2x(1) also optionally deploys admonition and navigation icons and a CSS stylesheet. See the a2x(1) man page for more details. All you need is xsltproc(1), DocBook XSL Stylesheets and optionally FOP (if you want PDF) or lynx(1) (if you want text).

The following example generates doc/quickstart.pdf from the AsciiDoc doc/quickstart.txt source file:

$ a2x -f pdf doc/quickstart.txt

See the a2x(1) man page for details.


	Use the `—verbose` command-line option to view executed toolchain commands.

AsciiDoc DocBook XSL Drivers

You will have noticed that the distributed PDF, HTML and HTML Help documentation files (for example ./doc/asciidoc.html) are not the plain outputs produced using the default DocBook XSL Stylesheets configuration. This is because they have been processed using customized DocBook XSL Stylesheet drivers along with (in the case of HTML outputs) the custom ./stylesheets/docbook.css CSS stylesheet.

You'll find the customized DocBook XSL drivers along with additional documentation in the distribution ./docbook-xsl directory. The examples that follow are executed from the distribution documentation (./doc) directory.

common.xsl

Shared driver parameters. This file is not used directly but is included in all the following drivers.

chunked.xsl

Generate chunked XHTML (separate HTML pages for each document section) in the ./doc/chunked directory. For example:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml

fo.xsl

Generate XSL Formatting Object (*.fo) files for subsequent PDF file generation using FOP. For example:

$ python ../asciidoc.py -b docbook article.txt
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
$ fop.sh article.fo article.pdf

htmlhelp.xsl

Generate Microsoft HTML Help source files for the MS HTML Help Compiler in the ./doc/htmlhelp directory. This example is run on MS Windows from a Cygwin shell prompt:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
$ mv htmlhelp.chm asciidoc.chm

manpage.xsl

Generate a roff(1) format UNIX man page from a DocBook XML refentry document. This example generates an asciidoc.1 man page file:

$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml

xhtml.xsl

Convert a DocBook XML file to a single XHTML file. For example:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html

If you want to see how the complete documentation set is processed take a look at the A-A-P script ./doc/main.aap.