Asciidoctor: AsciiDoc with new functions Performance Enhanced
Asciidoctor: AsciiDoc with new functions Performance Enhanced
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.
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.
Asciidoctor Variants
Asciidoctor EPUB3 [5] is not yet available as a package, but it works quite well with a few limitations. The aim is not only to translate into the EPUB3 format, but also to create an aesthetically pleasing design for ebooks. The option -a ebook-validate
automatically calls EPUBCheck.
Asciidoctor LaTeX [6] allows more extensive customization of the output with respect to the LaTeX code than AsciiDoc. This variant uses AMSTeX instead of standard LaTeX. This allows for more granular layout control. For example, unnecessarily extensive title pages are no longer required.
Asciidoctor PDF [7] allows direct conversion to PDF without the DocBook tool chain. The software is stable and comes with an additional component, a variant that generates more compact PDFs (asciidoctor-pdf-optimize
). The software lets you customize the output in terms of layout using a CSS-style mechanism.
The a2x
shell script lets users quickly and automatically convert source code to various output formats, especially to PDF. Additionally, it can evaluate options contained in the imported source code. This allows certain settings in the documents to be made in advance, such as the language and format of the output, as well as the document type. The instructions are written as comments in the lines directly after the document header. A call to a2x <file>
translates the document with all available options.
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
Table 1
Asciidoctor Command-Line Options
Option |
Effect |
|
Creates output as HTML5 (default), XHTML5, DocBook 5, manpage or – with appropriate plugins – as PDF, LaTeX, or EPUB |
|
Besides the classics |
|
Saves the output under the specified name |
|
Saves the result in the specified directory |
|
Suppresses headers and footers (for included documents) |
|
Auto numbering of sections |
|
Set AsciiDoc attributes (overwrites existing ones in the document) |
|
Defines the base directory for additional code; default is the current directory |
|
Outputs detailed messages |
|
Warning level, from which error codes were generated: |
|
Output warnings on screen |
|
Sets safe mode level; disables potentially insecure structures like |
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.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
Kubuntu Focus Announces XE Gen 2 Linux Laptop
Another Kubuntu-based laptop has arrived to be your next ultra-portable powerhouse with a Linux heart.
-
MNT Seeks Financial Backing for New Seven-Inch Linux Laptop
MNT Pocket Reform is a tiny laptop that is modular, upgradable, recyclable, reusable, and ships with Debian Linux.
-
Ubuntu Flatpak Remix Adds Flatpak Support Preinstalled
If you're looking for a version of Ubuntu that includes Flatpak support out of the box, there's one clear option.
-
Gnome 44 Release Candidate Now Available
The Gnome 44 release candidate has officially arrived and adds a few changes into the mix.
-
Flathub Vying to Become the Standard Linux App Store
If the Flathub team has any say in the matter, their product will become the default tool for installing Linux apps in 2023.
-
Debian 12 to Ship with KDE Plasma 5.27
The Debian development team has shifted to the latest version of KDE for their testing branch.
-
Planet Computers Launches ARM-based Linux Desktop PCs
The firm that originally released a line of mobile keyboards has taken a different direction and has developed a new line of out-of-the-box mini Linux desktop computers.
-
Ubuntu No Longer Shipping with Flatpak
In a move that probably won’t come as a shock to many, Ubuntu and all of its official spins will no longer ship with Flatpak installed.
-
openSUSE Leap 15.5 Beta Now Available
The final version of the Leap 15 series of openSUSE is available for beta testing and offers only new software versions.
-
Linux Kernel 6.2 Released with New Hardware Support
Find out what's new in the most recent release from Linus Torvalds and the Linux kernel team.