Conversion

Compiling – that is, converting – the source text into the desired format is a command-line process:

$ asciidoc <options> <source text>

The most important option is -b, which defines the output format. For formats such as PDF or EPUB, AsciiDoc needs a toolchain to generate the desired results. The default AsciiDoc installation comes with the a2x Python script as a wrapper. It uses a syntax incompatible with asciidoc for the most part and requires many additional tools, such as EpubCheck or the DocBook utilities.

Alternatively, you can use the Ruby script asciidoctor, which also adds advanced features. Again, it is incompatible with the asciidoc command in many places and with a2x.

Because Asciidoctor [7] is not featured in the repositories of the popular distributions, your only option is a manual install. Although this is unproblematic, the installation is only for the current user by default. The code is available as a gem on RubyGems.org and is installed as follows:

$ gem install asciidoctor

This assumes that you have a Ruby installation in place, and it will also install JRuby, the Java variant of Ruby along with a number of special fonts. If all of this works, with a simple call to

asciidoctor <filename>

you can then convert AsciiDoc files.

a2x

In many cases, a2x proves to be the easier option and offers a sufficiently large feature set to help you generate other formats from AsciiDoc. This tool can generate all the formats stated in Table 7. The argument to the -f option defines the format. In addition to a variety of HTML-based formats, a2x also supports EPUB- and DocBook-based formats such as PDF, PS, and DVI. With some restrictions, you can also create LaTeX source files and text-only files.

For the PDF and PS formats, but not for the totally obsolete DVI, a2x relies on two different approaches. By default, it uses dblatex ("DocBook LaTeX"), which often generates errors that prevent the conversion process from concluding successfully. The error messages often lack decisive information, so troubleshooting can be a time-consuming process. For this reason, the Apache FOP (Formatting Objects Processor) [8] is often a better choice.

In addition to PDF, a2x also creates SVG and various bitmap formats. What really impresses here is the robustness. It is much easier to create PDFs with --fop than with dblatex, even if the typography isn't always attractive.

The -k option prevents a2x from deleting temporary files. The file you will be particularly interested in for debugging is inputfile.xml. The xmllint XML checker, which is automatically called during conversion, ideally produces an error message (Listing 6). If an error occurs, the checker outputs a line in the XML file and the error the tool discovered.

As in LaTeX, the stated line doesn't necessarily contain the error; however, the details do help you close in on the problem. The error message is even less useful than in LaTeX when it comes to identifying the error type – but a little practice will help you here.

If you disable verification by xmllint (-L), you can speed up the conversion process; however, this will mean that it is virtually impossible to discover errors. Table 8 has more details of the program's features.

One more special feature in a2x is worthy of note: The tool can evaluate comments at the start of the source text and derive further conversion options from them.

The documentation describes this method by reference to an example of what to do if you cannot disable enumeration of sections using :numbered!: [9]. The last three lines in Listing 7 take care of this.

Conclusions

AsciiDoc can leave you with mixed feelings. Although the syntax is basically quite simple, it comes at the cost of reliability. Problems are inevitable given complex structures such as nested elements or the use of source code as part of the text, and it is often difficult to troubleshoot errors.

The developers have not learned from decades of experience with LaTeX when it comes to speed and error handling: In both cases, AsciiDoc does not offer any major benefits. In terms of extensibility and quality of the (PDF) output, LaTeX is miles ahead. However, this all changes when it comes to HTML-based formats such as EPUB. AsciiDoc is better suited to these tasks – unless, that is, you need a feature that the developers didn't intend you to use in a particular way.

On the positive side, the format is simple, and you can create the source text in any editor and still make sense of it in most cases. However, readability is quickly affected as the complexity of the source text increases.