From one to many: AsciiDoc converts a text file to various output formats

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.

Table 7

a2x Formats

Argument

Result

chunked

HTML in multiple files

xhtml

Extended HTML

htmlhelp

HTML variant

manpage

Man page format (troff)

pdf

Various PDF variants

dvi

Classic TeX format

ps

PostScript

tex

LaTeX

docbook

DocBook

text

Text output

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.

Listing 6

xmllint Output

 

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.

Table 8

a2x Options

Option

Function

-d <type>

Document type (e.g., article)

-f <format>

Output format (e.g., epub)

-k

Keep temporary files

--fop

Use FOP for PDF output

--fop-opts=<options>

Pass options to FOP

--icons

Integrate icons in the output

-v

Generate verbose messages

-L

Do not use xmllint

-r <path>

Retrieve resources from stated path

-a <attributes>

Define AsciiDoc attributes

--asciidoc-opts=<options>

Define AsciiDoc options

--conf-file=<filename>

Additional configuration file

-D <path>

Path for output file

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.

Listing 7

a2x Conversion Options

 

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.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Asciidoctor

    The popular AsciiDoc documentation system still has a lot to offer, but more experienced users should check out Asciidoctor, which has some additional new features.

  • Command Line – unoconv

    A hidden utility in the LibreOffice toolbox, unoconv offers a wide array of import and export filter options for use at the command line.

  • Introduction

    This month in Linux Voice.

  • Mermaid

    Mermaid lets you create diagrams from simple text-based statements.

  • Caddy

    Caddy lets even the most inexperienced user set up a secure web server.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More

News