AsciiDoc User Guide

$ 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.

FOP

XSL Stylesheets can be used to generate FO (Formatting Object) files, which in turn can be used to produce PDF files using the Apache Formatting Object Processor program (FOP). The FOP home page is at http://xml.apache.org/fop/.

As of version 0.20.5 installation and configuration of FOP is a manual process. You also need a working Java Runtime to run FOP. You'll find FOP and Java installation information in the appendices.

Tip

Once you've got FOP installed use the AsciiDoc a2x(1) toolchain wrapper to generate PDF files from AsciiDoc source.

Generating Plain Text Files

AsciiDoc does not have a text backend (for most purposes AsciiDoc source text is fine), however you can convert AsciiDoc text files to formatted text using the AsciiDoc a2x(1) toolchain wrapper utility.

XML and Character Sets

The default XML character set UTF-8 is used when AsciiDoc generates DocBook files but this can be changed by setting the xmldecl entry in the [attributes] section of the docbook.conf file or by composing your own configuration file [header] section).

Tip

If you get an undefined entity error when processing DocBook files you'll may find that you've used an undefined HTML character entity. An easy (although inelegant) fix is to use the character's character code instead of it's symbolic name (for example use   instead of

 ).

If your system has been configured with an XML catalog you may find a number of entity sets are already automatically included.

70