AsciiDoc [1] is a publication and documentation system, as well as a markup and formatting language. The simple syntax and clear-cut markup make source code edited with AsciiDoc easy to read directly.

However, those familiar with AsciiDoc may be interested in the additional features available with Asciidoctor. While Asciidoctor is designed for compatibility with AsciiDoc, there are points at which it differs from the original, including greater speed and a number of useful features.

New Capabilities

AsciiDoc's first versions date back to 2002. Today the packages are part of the standard feature set in many distributions and can be imported from their repositories. Besides HTML and XHTML, AsciiDoc supports the DocBook output format, which is useful as source material for generating specially formatted HTML, PDF, EPUB, DVI, LaTeX, roff, and PostScript files.

The AsciiDoc documentation system is based on Python 2, which is no longer supported. Before an AsciiDoc version adapted to the new Python 3 was released in June 2020, some interesting AsciiDoc variants were created – most notably Asciidoctor [2]. Asciidoctor's developers ensured its very extensive compatibility with AsciiDoc through more than 2,500 tests. They also implemented the program in Ruby, which speeds up conversion by a factor of about 100 compared to the classic Python variant. Later implementations in Java and JavaScript were added to support editing source code directly in the web browser [3].

Asciidoctor has a number of additional benefits [4]. One is that it extends the capabilities of the parser (i.e., the part of the program that reads and analyzes the input), which helps it support more complex constructions. Another benefit is a plugin system that allows for additional features such as special charts and the implementation of additional output formats, such as optimized PDFs, without the need to detour via DocBook as well as complex LaTeX and XHTML5.

There are also special Asciidoctor variants for different output formats, on which the developers work independently of the main distribution (currently version 2.0.10). For many editors there are plugins that help with the syntax and partly support compiling. The "Asciidoctor Variants" box looks at the most important examples. All of the converters mentioned are independent projects and accordingly have different documentation. Each of them achieves quite useful results. However, all of the variants require training if you need formatting that differs from the default settings.

Installing Asciidoctor

Normally, you would install Asciidoctor from your distribution's repository. However, if some components are missing, such as asciidoctor-epub3, you can use Ruby's own gem installation system and import the missing components, or gems, directly from the Ruby repository:

$ gem install asciidoctor-epub3

The tool installs the gems in ~/.gem/ruby/2.7.0/bin/. You must include this path in the system PATH variable.

In some cases, as in the example of asciidoctor-epub3, there are no packages officially available as of yet, and you will receive an error message. If there are packages that are still under development, you can test them with the --pre option:

$ gem install asciidoctor-epub3 --pre

In this case, the installation will be performed and more packages will be added.

The packages available in the gem repositories for Asciidoctor are shown by this command:

$ gem search asciidoctor

Again, --pre will reveal unfinished packages if necessary.

Differences

AsciiDoc and Asciidoctor differ in some details. For simple documents, this is at most a minor issue. However, if you make full use of the capabilities of each piece of software, the differences become more apparent. You will find examples of both AsciiDoc and Asciidoctor extensions in the AsciiDoc Syntax Quick Reference [8] – search for the (Asciidoctor only) string, which designates these features. In most cases the capabilities of Asciidoctor go beyond what AsciiDoc supports, however thanks to the built-in compatibility mode, Asciidoctor can handle anything you formatted with AsciiDoc. Having said this, the newcomer does not offer a counterpart for the command a2x, see box, "AsciiDoc's a2x Command."

Alternatively, you can specify the options at the shell prompt. As a special feature, a2x has the --epubcheck option to automate the process of calling the a2x tool, which identifies potential problems in EPUB documents.

Like AsciiDoc, Asciidoctor is usually controlled via the command line. The most important options, which are very similar to those of AsciiDoc, are summarized in Table 1. A command call without options translates the specified file with the .adoc extension to HTML5:

$ asciidoctor tst.adoc

By default the tool suppresses messages during conversion. It only shows you serious errors, such as the absence of embedded images. But this does not stop further editing.

When switching from AsciiDoc to Asciidoctor, there are some differences to be considered, which are summarized in chapter 90 of the user manual [9].

For example, in terms of the syntax, there is now only the _<Text>_ syntax for text in italics, `<Text>` for code, and `+{<Text>}+` for literal text in code. Double quotation marks are created with "`<Text>`", as well as single quotation marks with '`<Text>`'.

For titles, the = <Title> syntax (asymmetrical form) remains valid, but not the symmetrical form (= <Title> =) or the form using underlining. Underlining in the title automatically leads to the use of compatibility mode. Section 90.8 in the manual also provides an overview of new or additional features.

Asciidoctor now supports UI macros for keyboard shortcuts (Figure 1). Also interesting in Asciidoctor is the standard approach of writing each sentence as one line of the source code, in the manner common for program code. This allows for sentence swapping, commenting out, and other manipulation much like in any programming language.

Figure 1: These UI macros for keyboard shortcuts are available in Asciidoctor, but not in AsciiDoc. © https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#more-delimited-blocks