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.
![Learn More](https://www.linux-magazine.com/var/linux_magazin/storage/images/media/linux-magazine-eng-us/images/misc/learn-more/834592-1-eng-US/Learn-More_medium.png)
News
-
NVIDIA Released Driver for Upcoming NVIDIA 560 GPU for Linux
Not only has NVIDIA released the driver for its upcoming CPU series, it's the first release that defaults to using open-source GPU kernel modules.
-
OpenMandriva Lx 24.07 Released
If you’re into rolling release Linux distributions, OpenMandriva ROME has a new snapshot with a new kernel.
-
Kernel 6.10 Available for General Usage
Linus Torvalds has released the 6.10 kernel and it includes significant performance increases for Intel Core hybrid systems and more.
-
TUXEDO Computers Releases InfinityBook Pro 14 Gen9 Laptop
Sporting either AMD or Intel CPUs, the TUXEDO InfinityBook Pro 14 is an extremely compact, lightweight, sturdy powerhouse.
-
Google Extends Support for Linux Kernels Used for Android
Because the LTS Linux kernel releases are so important to Android, Google has decided to extend the support period beyond that offered by the kernel development team.
-
Linux Mint 22 Stable Delayed
If you're anxious about getting your hands on the stable release of Linux Mint 22, it looks as if you're going to have to wait a bit longer.
-
Nitrux 3.5.1 Available for Install
The latest version of the immutable, systemd-free distribution includes an updated kernel and NVIDIA driver.
-
Debian 12.6 Released with Plenty of Bug Fixes and Updates
The sixth update to Debian "Bookworm" is all about security mitigations and making adjustments for some "serious problems."
-
Canonical Offers 12-Year LTS for Open Source Docker Images
Canonical is expanding its LTS offering to reach beyond the DEB packages with a new distro-less Docker image.
-
Plasma Desktop 6.1 Released with Several Enhancements
If you're a fan of Plasma Desktop, you should be excited about this new point release.