AsciiDoc

AsciiDoc gehört wie Markdown zu den Auszeichnungssprachen (markup languages). Das Projekt startete einst als Implementierung in Python und wurde danach unter dem Namen AsciiDoctor fortgeführt, wobei eine Neuimplementierung in Ruby erfolgte. Mittlerweile gibt es auch eine Implementierung in JavaScript, die im Zuge des Projektes Antora entstand, auf das hier aber nicht näher eingegangen werden soll.

AsciiDoc wird viel in der Java-Community eingesetzt, wobei hier in der Regel nicht die native Ruby-Toolchain zum Einsatz kommt, sondern entsprechende Plugins für die gängigen Java-Buildtools, wie das asciidoctor-maven-plugin für Maven. Letztes Jahr wurde das Projekt standardisiert und unter das Dach der Eclipse Foundation gestellt, um die Zukunft des Projektes zu gewährleisten.

Mittlerweile unterstützen auch GitHub, GitLab, Gitea (muss in der app.ini als externes Tool konfiguriert werden) und Bitbucket (mittels Plugin) AsciiDoc Dokumente, sodass man seine README-Dateien in AsciiDoc schreiben kann.

Wieso nicht einfach Markdown?

Manch einer wird sich natürlich jetzt schon die Frage gestellt haben, wieso man nicht einfach Markdown verwenden kann? Meiner Meinung nach ist das keine Frage des Oders, sondern des Unds. Für alles, was relativ einfach gehalten ist, keine Tabellen braucht und weniger als 2 Seiten umfasst, verwende ich eher Markdown. Es ist weiter verbreitet, mehr Tools unterstützen es und es ist leichtgewichtiger.

Sobald es aber um größere Dokumente geht oder ich Fußnoten oder komplexere Tabellen brauche, greife ich zu AsciiDoc. Ein weiterer Vorteil von AsciiDoc ist, dass es einen Standard gibt und nicht wie bei Markdown mehrere Dialekte, die unterschiedlich gut von den jeweiligen Tools unterstützt werden.

Was bietet AsciiDoc?

Unter anderem:

• Automatische Erstellung von Inhaltsverzeichnissen
• Mathematische Formeln mittels AsciiMath und/oder Latex
• Kopfzeilen und Fußnoten Unterstützung
• Unterstützung von Querverweisen
• Unterstützung von komplexen Tabellen
• Einbettung von Audio bzw. Video (abhängig vom Exportformat)
• Direktes Einbetten von PlantUML

Beispiele

Eine einfache Tabelle in AsciiDoc sieht wie folgt aus:

asciidoc
.Einfache Tabelle
[cols="1,1,1"]
|===

| ID | Nachname | Vorname

| 1
| Riker
| William Thomas

| 42
| Adams
| Douglas

| 4711
| Mustermann
| Max

| 5773
| Hopper
| Grace

|===

Als html-Output wird dies gerendert zu:

Eine komplexere Tabelle lässt sich zum Beispiel so aufbauen:

asciidoc
//Schaltet die Mathe-Unterstützung ein
:stem:

.Komplexe Tabele
[cols="1,3,1"]
|===

| 1. Spalte
| 2. Spalte
| 3. Spalte

| AsciiMath-Formel: stem:[sqrt(4) = 2]
a| * Erstes Listenelement
* Zweites Listenelement
* Drittes Listenelement Latex-Formel: latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]
a|
== Code
[source, ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

| Albert Einstein
2.2+^.^| stem:[E_0 = m*c²]

| Mileva Marić

|===

Wieder ein Screenshot eines html-Exports:

Exportformate

AsciiDoc-Dokumente können prinzipiell in eine Vielzahl von Formaten mittels Konverter exportiert werden. Hierbei zu unterscheiden sind fest eingebaute Konverter und Konverter, die als Add-On zur Verfügung stehen. Bei letzteren gibt es wiederum offizielle, vom AsciiDoc-Projekt unterstützte Add-Ons und inoffizielle. Fest eingebaute Konverter bieten Exportmöglichkeiten nach html, xhtml, DocBook und Man-Pages. Als offizielle Add-On-Konverter stehen unter anderem Konverter für die Erzeugung von PDFs und EPUB3 zur Verfügung.

Tooling-Unterstützung

Um AsciiDoc-Dokumente zu erstellen, ist entweder die Ruby basierte Toolchain notwendig oder das oben bereits erwähnte Maven-Plugin. Plugins stehen für mehrere Editoren/IDEs zur Verfügung unter anderem für:

• VSCodium
• Eclipse
• IntelliJ IDEA

Schlusswort

AsciiDoc ist eine sehr mächtige Auszeichnungssprache, mit der sich komplexe Dokumente bequem erstellen lassen.  
Vorteile gegenüber Markdown sind die mächtigere Syntax und die Standardisierung. Nachteil ist die aufwendigere Toolchain und dass es nicht ganz so verbreitet ist.

Interessant ist AsciiDoc in erster Linie für all diejenigen, die größere, komplexere Dokumente erstellen müssen und sich hierbei nicht mit DocBook abquälen wollen. Weniger interessant ist es für all diejenigen, die nur kurze einfache Dokumente verfassen. Hierfür bietet Markdown eigentlich alles, was man benötigt.

Ob Sphinx und Org-Mode Benutzer durch AsciiDoc etwas gewinnen würden, kann ich zwecks Unkenntnis nicht beantworten. Die Latexfraktion wird vermutlich keinen großen Mehrwert von AsciiDoc haben. Der native html-Export halte ich bei AsciiDoc für besser, aber das mag sich mittlerweile auch bei Latex gebessert haben oder es lag einfach nur an meiner Unkenntnis von Latex. Dafür hat Latex den besseren und direkten PDF-Export. (AsciiDoc geht beim PDF-Export über DocBook als Zwischenformat.)

Zum Schluss sei nur ganz kurz noch auf das Projekt DocToolChain verwiesen, das auf AsciiDoc setzt und das eine Vielzahl von Möglichkeiten bei der Erstellung von technischen Dokumentationen bietet, wie die Ansteuerung von Enterprise Architect für das automatische Inkludieren von UML-Diagrammen, den Export nach Word oder den direkten Deploy nach Confluence. Wen das Thema interessiert, der findet hier eine Artikelserie darüber.