AsciiDoc – einfach erklärt

Was ist AsciiDoc?

AsciiDoc ist eine vereinfachte Auszeichnungssprache, mit der man Texte in verschiedenen Dokumentenformaten veröffentlichen kann. Eine Auszeichnungssprache ist eine Sprache, bei der man normale Textdateien mit speziellen Zeichen versehen kann, um z. B. Überschriften, Fettschrift oder Listen zu markieren.

AsciiDoc-Dateien (Endungen .adoc oder .asciidoc) können nach HTML oder in das DocBook-Format umgewandelt werden – und von DocBook aus weiter in viele andere Formate wie PDF oder Manpage.

Der Vorteil gegenüber komplexen Formaten wie DocBook (die auf SGML oder XML basieren): AsciiDoc ist leicht zu lernen und auch ohne Verarbeitung, also als reiner Quelltext, gut lesbar. Weitere solche „leichten“ Auszeichnungssprachen sind Markdown, reStructuredText, Textile, Almost Plain Text und Wikitext. Einer breiten Öffentlichkeit wurde AsciiDoc durch den Einsatz auf GitHub bekannt.

Entwickelt wurde AsciiDoc von Stuart Rackham, die Erstveröffentlichung war 2002.

Software und Geschichte

Das ursprüngliche Konvertierprogramm heißt asciidoc: ein Dokumentwandler, geschrieben in Python, veröffentlicht unter der freien GNU General Public License (GPLv2). Es ist plattformunabhängig. Im Juni 2020 erschien eine an aktuelle Python-Versionen angepasste Version, aktuell ist Version 10.0.2 (13. November 2021).

Außerdem gibt es die Neuimplementierung Asciidoctor (Hauptentwickler Dan Allan), deren Version 0.1 im Jahr 2013 erschien; aktuell ist v2.0.17 (6. Januar 2022). Asciidoctor ist in Ruby geschrieben und unter der MIT-Lizenz frei verfügbar; GitHub nutzt es, um AsciiDoc-Dokumente nach HTML umzuwandeln. Es gibt auch Varianten für Java und JavaScript.

AsciiDoc Working Group

Am 6. Februar 2020 gab die Eclipse Foundation die Gründung der AsciiDoc Working Group bekannt. Ziel ist die Standardisierung von AsciiDoc. Die Open-Source-Organisation möchte einen „offenen und neutralen Raum für die Diskussionen und Entwicklungen zur Auszeichnungssprache schaffen, sowohl was die Sprache als auch das Dokumentmodell betrifft.“

Beispiel

Ein AsciiDoc-Dokument kann etwa so aussehen:

= Meine Überschrift erzeugt eine Hauptüberschrift, darunter steht der Autor, z. B. K. Mustermann.
== Software und == Hardware erzeugen Unterüberschriften.
Ein Link wird mit https://wikipedia.org[Wikipedia] geschrieben – im Ergebnis erscheint das Wort „Wikipedia“ als Verweis.
vielen ergibt fetten Text, 'paket' kursive Hervorhebung.
make zeichnet Programmcode aus.
Ein eingerückter Block wie „make install paket“ wird als Code-Beispiel dargestellt.
Mit * gefolgt von einem Leerzeichen (z. B. * Eisen, * Kupfer) erzeugt man eine Aufzählungsliste.

Die Angabe :encoding: iso-8859-1 in der ersten Zeile ist nur nötig, wenn das Dokument nicht in UTF-8 kodiert ist. Der AsciiDoc-Prozessor wandelt diesen Quelltext dann in ein formatiertes HTML-Dokument um.

Vergleich zu Wikitext

AsciiDoc ähnelt Wikitext, aber beide Sprachen sind für unterschiedliche Einsatzzwecke entwickelt worden:

Wikitext wurde für Webseiten entwickelt, speziell Wiki-Seiten. Verweise auf andere Wiki-Seiten sind sehr einfach, z. B. [[Beispiel]]. Original AsciiDoc hat dafür keine eigene Schreibweise; dort muss die volle URL angegeben werden, z. B. https://de.wikipedia.org/wiki/Beispiel[Beispiel].
AsciiDoc wurde für technische Dokumentation entwickelt, besonders im Bereich der Informatik. Dateinamen oder Programmcode lassen sich leicht im Fließtext auszeichnen: Beispiel ergibt Code-Text. In Wikitext braucht man dafür die längere Schreibweise <code>Beispiel</code>.
Ausgabeformate: MediaWiki kann Wikitext ohne Weiteres nur nach HTML umwandeln. AsciiDoc-Implementierungen bieten neben HTML auch PDF, DocBook, Manpage, EPUB und LaTeX. Daher eignet sich AsciiDoc auch für Bücher und Dokumente, die außerhalb des Webs gelesen werden sollen.