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
-
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
-
Juno Computers Launches Another Linux Laptop
If you're looking for a powerhouse laptop that runs Ubuntu, the Juno Computers Neptune 17 v6 should be on your radar.
-
ZorinOS 17.1 Released, Includes Improved Windows App Support
If you need or desire to run Windows applications on Linux, there's one distribution intent on making that easier for you and its new release further improves that feature.
-
Linux Market Share Surpasses 4% for the First Time
Look out Windows and macOS, Linux is on the rise and has even topped ChromeOS to become the fourth most widely used OS around the globe.
-
KDE’s Plasma 6 Officially Available
KDE’s Plasma 6.0 "Megarelease" has happened, and it's brimming with new features, polish, and performance.
-
Latest Version of Tails Unleashed
Tails 6.0 is based on Debian 12 and includes GNOME 43.
-
KDE Announces New Slimbook V with Plenty of Power and KDE’s Plasma 6
If you're a fan of KDE Plasma, you'll be thrilled to hear they've announced a new Slimbook with an AMD CPU and the latest version of KDE Plasma desktop.
-
Monthly Sponsorship Includes Early Access to elementary OS 8
If you want to get a glimpse of what's in the pipeline for elementary OS 8, just set up a monthly sponsorship to help fund its continued existence.
-
DebConf24 to be Held in South Korea
Busan will be the location of the latest DebConf running July 28 through August 4