Das vielseitige Dokumentationssystem Asciidoc basiert auf dem inzwischen obsoleten Python 2. Die Alternative Asciidoctor schafft Zukunftssicherheit.

Asciidoc [1] ist ein universelles Publikations- und Dokumentationssystem sowie eine Auszeichnungs- beziehungsweise Formatierungssprache. Durch die einfache Syntax und die klaren Auszeichnungen lassen sich mit Asciidoc bearbeitete Quelltexte ohne Weiteres direkt lesen.

Die ersten Versionen der Software stammen aus dem Jahr 2002 und sind damit deutlich älter als etwa die auf Asciidoc aufbauende Markdown-Syntax. Heute gehören die entsprechenden Pakete in vielen Distributionen zum Standard und lassen sich aus dem Repository einspielen.

Einen Vergleich der Markdown-Syntax mit der von Asciidoc finden Sie im Benutzerhandbuch [2]. Für viele Anwender ist aber vermutlich die “AsciiDoc Syntax Quick Reference” [3] eine effektivere Informationsquelle. Dort finden Sie Beispiele sowohl für Asciidoc als auch für die Asciidoctor-Erweiterungen. Suchen Sie nach der Zeichenkette (Asciidoctor only), die diese Features markiert.

Als Ausgabeformate unterstützt Asciidoc neben HTML und XHTML auch DocBook. Letzteres eignet sich als Ausgangsmaterial zum Erzeugen von speziell formatiertem HTML, PDF, EPUB, DVI, LaTeX, Roff und Postscript.

Bevor im Juni 2020 eine an das neue Python 3 angepasste Version der Sprache erschien, entstanden einige interessante Varianten von Asciidoc – allen voran Asciidoctor [4]. Dessen Entwickler stellten durch mehr als 2500 Tests seine sehr weitgehende Kompatibilität zu Asciidoc sicher. Außerdem implementierten Sie das Programm in Ruby, was das Konvertieren etwa um den Faktor 100 im Gegensatz zur klassischen Python-Variante beschleunigt. Später kamen Implementationen in Java und Javascript dazu, was das Bearbeiten der Quelltexte direkt im Webbrowser ermöglicht [5].

Die Neuimplementation hat noch eine Reihe weiterer Vorteile: So erweitert sie etwa die Fähigkeiten des Parsers, also des Programmteils, der die Eingaben liest und analysiert, und erlaubt damit komplexere Konstruktionen [6]. Ein Plugin-System ermöglicht zusätzliche Features wie spezielle Diagramme sowie das Implementieren zusätzlicher Ausgabeformate, etwa optimiertes PDF ohne Umweg über DocBook sowie komplexes LaTeX und XHTML5.

Für verschiedene Ausgabeformate gibt es zusätzlich spezielle Asciidoctor-Varianten, an denen Entwickler unabhängig von der Hauptdistribution (derzeit in der Version 2.0.10) arbeiten. Für viele Editoren existieren Plugins, die bei der Syntax helfen und teilweise das Kompilieren unterstützen. Die Tabelle “Asciidoctor-Varianten” erläutert die wichtigsten Vertreter.

Alle dort genannten Konverter sind eigenständige Projekte und entsprechend anders dokumentiert. Mit jedem davon erzielen Sie recht gute Ergebnisse. Alle Varianten erfordern aber ein Einarbeiten, wenn Sie von den Voreinstellungen abweichende Formatierungen benötigen.

$ gem install asciidoctor-epub3
$ gem install asciidoctor-epub3 --pre
$ gem search asciidoctor

Unterschiede

Asciidoc und Asciidoctor unterscheiden sich in einigen Details. Bei einfachen Dokumenten spielt das quasi keine oder nur eine untergeordnete Rolle. Reizen Sie die Möglichkeiten der jeweiligen Software aber voll aus, treten die Unterschiede zutage. So werten Asciidoc und Asciidoctor Attribute auf verschiedene Weise aus, was zu unterschiedlichen Ergebnissen führt (Abbildung 1).

Abbildung 1: Die Unterschiede zwischen Asciidoc (oben) und Asciidoctor zeigen sich etwa, wenn man die Auswirkungen von jeweils unbekannten Attributen betrachtet.

Es gibt aber noch viele weitere Unterschiede: In den meisten Fällen gehen die Möglichkeiten von Asciidoctor über das hinaus, was Asciidoc ermöglicht. Dank des eingebauten Kompatibilitätsmodus kann Asciidoctor jedoch alles verarbeiten, was Sie als Asciidoc formatiert haben. Der Newcomer bietet allerdings kein Pendant für den Befehl a2x (siehe Kasten “Einer für alles”).

Praxis

Wie Asciidoc bedienen Sie auch Asciidoctor in der Regel über die Befehlszeile. Die wichtigsten Optionen – sie entsprechen weitgehend denen von Asciidoc – fasst die Tabelle “Asciidoctor: Befehlszeilenoptionen” zusammen. Ein Befehlsaufruf ohne Optionen übersetzt die angegebene Datei mit der Endung .adoc nach HTML5:

$ asciidoctor tst.adoc

Voreingestellt unterdrückt das Tool Meldungen beim Konvertieren. Es zeigt lediglich schwerwiegende Fehler an, wie etwa das Fehlen eingebundener Bilder. Das stoppt das weitere Bearbeiten aber nicht.

Beim Umstieg von Asciidoc zu Asciidoctor gibt es einige Unterschiede zu beachten, die das Kapitel 90 im Benutzerhandbuch [7] zusammenfasst. Für die meisten Anwender dürften nur wenige Unterschiede wirklich relevant sein, etwa bei der Syntax. So gibt es für kursiven Text nur noch die Schreibweise _Text_, für Code nur noch `Text`, für literalen Text im Code nur `+{Text}+`. Doppelte Hochkommas erzeugen Sie durch "`Text`", einfache über '`Text`'. Asciidoctor erlaubt nun unter anderem abgekürzte Schreibweisen für Zitate, die Asciidoc nicht kennt. Dasselbe gilt für die sogenannten UI-Makros, die Tastenkürzel symbolisieren (Abbildung 2).

Abbildung 2: UI-Makros für Tastenkürzel gibt es bei Asciidoctor, nicht aber bei Asciidoc. Die Abbildung zeigt ein Beispiel aus der Dokumentation.

Bei Titeln greift nur noch die Syntax = Titel (asymmetrische Form), jedoch nicht mehr die symmetrische Form (= Titel =) und die Form mittels Unterstreichung. Unterstreichungen im Titel führen automatisch zum Einsatz des Kompatibilitätsmodus. Abschnitt 90.8 im Handbuch gibt außerdem eine Übersicht über neue oder zusätzliche Features.

Interessant ist die für Asciidoctor normale Schreibweise, jeden Satz in eine Zeile des Quelltexts zu schreiben, wie das etwa bei Programmcode üblich ist. Das ermöglicht Satzvertauschungen, das Auskommentieren oder Ähnliches wie in jeder Programmiersprache.

Wege zum PDF

Die klassische Struktur von Asciidoc orientiert sich mehr oder weniger direkt an HTML, was das Konvertieren in die darauf aufbauenden Formate einschließlich EPUB erleichtert. Wer eher lineare Dokumente wie Bücher erzeugen will, bevorzugt in der Regel PDF. Es gibt mehrere Wege, mit teilweise recht unterschiedlichen Ergebnissen, um dieses Format zu erzeugen.

Zum einen besteht die Möglichkeit, den Webbrowser zu nutzen. Man erzeugt eine HTML-Ausgabe, ruft sie im Browser auf und exportiert sie daraus als PDF. Der Vorteil: Dieser Weg unterstützt CSS-Optionen recht weitgehend. Alternativ nutzt man über A2x die Docbook5-Toolchain. Bei Asciidoctor erzeugt man mittels Asciidoctor-PDF direkt PDF. Das funktioniert eigentlich immer, oft aber nur mit mäßigen Ergebnissen.

Asciidoc eröffnet einen Weg über eine FOP-Umwandlung. Das funktioniert nicht immer problemlos, der Prozess ist aber recht schnell. Der Nachteil liegt darin, dass es keine vernünftigen Fehlermeldungen gibt und Fehler so oft lange unentdeckt bleiben.

Als dritte Option bleibt der Weg über LaTeX. Dabei erzeugen Sie mittels Asciidoc oder Asciidoctor entsprechenden Code, den Sie auf konventionelle Weise mit den LaTeX-eigenen Werkzeugen umwandeln. Das ermöglicht hochwertige Druckausgaben, erfordert aber zusätzliches LaTeX-Know-how und oft manuelle Feinarbeiten.

Unabhängig davon, welchen Weg Sie wählen: Interaktive Elemente gehen immer weitgehend verloren (Abbildung 3).

Abbildung 3: Interaktive Strukturen bei den HTML-Ausgabeformaten, wie etwa Click-Blocks, erlaubt nur Asciidoctor. Ein Mausklick auf Answer zeigt dann die im Quelltext vorgegebene Antwort (Beispiel aus der Originaldokumentation).

Fazit

Asciidoctor erweist sich als würdiger Nachfolger für Asciidoc. Die schnelle Arbeitsgeschwindigkeit und die zusätzlichen Plugins sowie die direkte Unterstützung in AsciidocFX [11] machen es zu einer guten, wenn auch komplexeren Alternative.

Gibt es nun also gar keinen Grund mehr, Asciidoc zu verwenden? Das kommt darauf an: Eine gut funktionierende Toolchain, etwa für E-Books, ist nicht zu verachten. Auch fallen die Ergebnisse speziell für diesen Fall manchmal kompakter aus als die Resultate von Asciidoctor-EPUB3. Zudem liegt die Komplexität bei der Arbeit mit Asciidoctor deutlich höher als bei Asciidoc; die zusätzlichen Möglichkeiten erschweren die Suche nach Fehlern.

Insgesamt macht die um Asciidoctor herum entstandene Infrastruktur einen deutlich agileren Eindruck. Es lohnt sich also für erfahrene Anwender, einen Umstieg zu prüfen. Für Einsteiger empfiehlt sich dagegen aufgrund der einfachen Handhabung das klassische Asciidoc. Wer darin sicher ist, meistert den Wechsel zu Asciidoctor später leichter. (jlu)