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) |
|
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.
Infos
- AsciiDoc: http://asciidoc.org
- List continuation: http://www.methods.co.nz/asciidoc/userguide.html#X15
- Documentation: http://www.methods.co.nz/asciidoc/userguide.html
- Sample article: http://asciidoc.org/article-standalone.html
- User guide as AsciiDoc file: http://asciidoc.org/asciidoc.txt
- Book template: http://www.methods.co.nz/asciidoc/book.html
- Asciidoctor: http://asciidoctor.org
- Apache FOP: https://en.wikipedia.org/wiki/Formatting_Objects_Processor
- Publishing eBooks: http://asciidoc.org/publishing-ebooks-with-asciidoc.html
« Previous 1 2
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
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.
News
-
Linux Servers Targeted by Akira Ransomware
A group of bad actors who have already extorted $42 million have their sights set on the Linux platform.
-
TUXEDO Computers Unveils Linux Laptop Featuring AMD Ryzen CPU
This latest release is the first laptop to include the new CPU from Ryzen and Linux preinstalled.
-
XZ Gets the All-Clear
The back door xz vulnerability has been officially reverted for Fedora 40 and versions 38 and 39 were never affected.
-
Canonical Collaborates with Qualcomm on New Venture
This new joint effort is geared toward bringing Ubuntu and Ubuntu Core to Qualcomm-powered devices.
-
Kodi 21.0 Open-Source Entertainment Hub Released
After a year of development, the award-winning Kodi cross-platform, media center software is now available with many new additions and improvements.
-
Linux Usage Increases in Two Key Areas
If market share is your thing, you'll be happy to know that Linux is on the rise in two areas that, if they keep climbing, could have serious meaning for Linux's future.
-
Vulnerability Discovered in xz Libraries
An urgent alert for Fedora 40 has been posted and users should pay attention.
-
Canonical Bumps LTS Support to 12 years
If you're worried that your Ubuntu LTS release won't be supported long enough to last, Canonical has a surprise for you in the form of 12 years of security coverage.
-
Fedora 40 Beta Released Soon
With the official release of Fedora 40 coming in April, it's almost time to download the beta and see what's new.
-
New Pentesting Distribution to Compete with Kali Linux
SnoopGod is now available for your testing needs