Die meisten Texte werden 2021 immer noch mit Microsoft Word oder einem der Konkurrenten (OpenOffice Writer, Libre Office Writer, TextMaker oder AbiWord) geschrieben. Die Vorteile dieser WYSIWYG-Editoren liegen auf der Hand; der Text sieht schon beim Editieren so aus, wie er am Ende ausgedruckt aussehen wird (zumindest sollte das der Fall sein).

Trotzdem hat sich in den vergangenen 15 Jahren mit dem von John Gruber, Betreiber des bekannten Blogs Daring Fireball, entwickelten Markdown eine Alternative etabliert, bei der das nicht der Fall ist. Markdown ist eine sogenannte vereinfachte Auszeichnungssprache, bei der der Schreiber seinen Text mit leicht kryptischen Formatierungsanweisungen anreichert, und das Ergebnis während des Erstellen bestenfalls in einem Preview neben dem eigentlichen Text zu sehen bekommt.

Der Grund für diesen scheinbaren Rückschritt ist die Tatsache, dass immer mehr Texte in unleserlichen Formaten wie PDF, HTML oder EPUB benötigt werden. Im Vergleich zu diesen ist Markdown aus menschlicher Sicht einfach zu lesen und zu schreiben, und dient somit als Grundlage für die Konvertierungen in die Zielformate, die dann meist maschinell - vom Browser, vom PDF-Viewer, vom Ebook-Reader usw. - ausgewertet werden. Darüber hinaus ist Markdown gänzlich plattformunabhängig, sehr leichtgewichtig und es erlaubt dem Autor/Blogger seinen Lieblingseditor zu verwenden.

Damit der Text leicht zu lesen ist, sind die Markierungen in Markdown sehr einfach gehalten. Eine Überschrift wird mit einer oder mehreren Rauten(#) eingeleitet, ein Wort durch umschließende Asterisk(*) kursiv gesetzt, ein Link durch spitze Klammern gekennzeichnet, um ein paar Beispiele zu nennen. Diese einfache Syntax, die Markdown zum Erfolg verholfen hat, steckt aber auch die Grenzen des Projekts.

AsciiDoc: Markdown++

Markdown ist schnell überfordert, wenn es doch etwas komplexer werden muss, wenn etwa eine Fußnote, ein Index oder ein Querverweis benötigt wird. In der Praxis existiert für diese Fälle zwar eine Reihe von Dialekten (Flavours), diese sind aber untereinander nicht kompatibel und weichen das Format dadurch auf. Als Beispiel sei das oft verwendete GitHub Flavored Markdown genannt.

Eine Alternative, die die genannten Aufgaben aus dem Stand beherrscht, ist AsciiDoc, ebenfalls ein Vertreter der vereinfachten Auszeichnungssprachen. Ähnlich alt wie Markdown, aber längst nicht so bekannt, bietet es seine Dienste als “mature, plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more” an. AsciiDoc ist ebenfalls leicht zu schreiben, die Lesbarkeit des Textes ist gefühlt ein klein wenig schlechter als die eines Markdown-Textes.

Das Projekt besteht aus zwei Teilen: Der Spezifikation des Formats und einem Konverter, mit dessen Hilfe sich der Rohtext in das Zielformat überführen lässt. Kosten fallen für die Software keine an, AsciiDoc ist freie Software und steht unter der GPLv2-Lizenz.

AsciiDoc-Grundlagen

Die AsciiDoc-Syntax ist auf der Homepage des Projekts ausführlich erklärt, um einen Eindruck zu bekommen, werden hier die wichtigsten Formatierungen vorgestellt.

Die Gliederung eines Dokuments in Sektionen, Subsektionen usw. erfolgt in AsciiDoc mit Gleichzeichen (=). Der Titel des Dokuments mit einem Gleichzeichen, die erste Ebene mit zweien und so weiter. Diese Sektionen werden im Normalfall auch als Überschriften angezeigt. Die oberste Überschrift, der Dokumenttitel, ist dabei Teil des Headers, in dem sich bei Bedarf ergänzende Informationen wie zum Beispiel der Name des Autors und ein Untertitel unterbringen lässt.

= Dokumenttitel (Teil des Header)

== 1. Gliederungsebene

== 2. Gliederungsebene

Das Wort Paragraph wird in der deutschen Sprache meist mit einem Gesetzestext in Zusammenhang gebracht. Ein Paragraph in AsciiDoc ist aber einfach ein Textabschnitt (vergleichbar mit <p> in HTML). Hier ist wenig zu beachten, es sind keine besonderen Formatierungsanweisungen erforderlich. Vom darauf folgenden Textabschnitt wird er durch eine Leerzeile getrennt.

Innerhalb des Textes müssen oft Wörter hervorgehoben werden, dies geschieht durch Schriftstilvarianten. Variiert werden kann die Stärke (fett), die Lage (kursiv) und die Breite (monospaced) der Schrift:

Variiert werden kann die *Stärke* (fett), die _Lage_(kursiv) und die `Breite` (monospaced) der Schrift.

Natürlich sind auch Kombinationen von Hervorhebungen erlaubt.

Listeneinträge werden wie in Markdown durch vorangestellte Asteriske gekennzeichnet:

* ein Eintrag
* ein weiterer Eintrag
* und ein Dritter

Auch für Links bietet AsciiDoc eine im Rohtext gut zu lesende Syntax. Das Linkziel wird in den Text eingefügt und der statt der URL darzustellende Text in eckigen Klammern direkt hinter dem Link aufgeführt. Ein Link auf die AsciiDoc-Webseite sieht also beispielsweise folgendermaßen aus:

Ein https://asciidoc.org[Link auf die AsciiDoc-Webseite] sieht also beispielsweise folgendermaßen aus:

Bilder werden durch ein vorangestelltes image gekennzeichnet. Hinter zwei Doppelpunkten folgen dann Pfad und Name des Bildes und bei Bedarf ein alternativer Text in eckigen Klammern. Eventuell vorhandene Bildunterschriften werden durch einen vorangestellten Punkt markiert:

image::atom.png[Atom]
.AsciiDoc-Preview in Atom

Die Darstellung von Quellcode mit Syntax-Highlighting erfolgt durch Einschliessen des Codes in mindestens vier aufeinanderfolgende Bindestriche. Die verwendete Programmiersprache wird dabei als Stilanweisung vor den Block gestellt:

[source, java]
----
@Data
@Entity
public class Address {
  @Id @GeneratedValue(strategy=GenerationType.AUTO)   # <1>
  private Long id;

  private String firstname;
  ...
----
<1> Identifier, wird automatisch erzeugt

Mit Hilfe sogenannter Callouts lassen sich einzelne Zeilen des Quellcodes erklären. Die Zeile bekommt zu diesem Zweck eine Nummer in spitzen Klammern und wird im Anschluss an den Codeabschnitt erläutert:

[source, java]
--------------------------------------
@Data
@Entity
public class Address {

  @Id @GeneratedValue(strategy=GenerationType.AUTO)   # <1>
  private Long id;

  private String firstname;
--------------------------------------
<1> Mit diesem Callout lässt sich die Zeile näher beschreiben

AsciiDoc für Fortgeschrittene

Damit sind die Formatierungsanweisungen für den Großteil aller Texte beschrieben. Bis hierhin ist Markdown ähnlich leistungsfähig und wegen der weiteren Verbreitung zu bevorzugen. Wer aber eine Diplomarbeit, ein Fachbuch oder eine komplexe Dokumentation schreiben möchte, kommt mit Markdown an die Grenzen. Hier spielen dann Themen wie Fußnoten, Querverweise, Literaturverzeichnis, Index, Glossar, Anhang und Inhaltsverzeichnis eine wichtige Rolle. Alle diese Aufgaben (und noch viele mehr) lassen sich mit AsciiDoc perfekt lösen, das Format wurde eigens konzipiert, um damit Bücher zu schreiben.

Ein Inhaltsverzeichnis beispielsweise lässt sich relativ leicht aus den erwähnten Sektionen (Überschriften) generieren. Um das Inhaltsverzeichnis anzuzeigen, ist die Anweisung :toc: nach dem Header erforderlich:

= AsciiDoc: Wenn Markdown an die Grenzen kommt
Von Dirk Koller
:toc:

Zumindest für ein gedrucktes Fachbuch wird man sicher einen Index benötigen, der die Stichworte in alphabetischer Reihenfolge auflistet. Das ist mit AsciiDoc ein Kinderspiel, das betroffene Wort wird einfach an der Stelle, die im Index gelistet werden soll, in doppelte runde Klammern gesetzt. Ans Ende des Dokuments kommt noch eine Level1-Sektion mit dem Stil index, die dafür sorgt das der Index an dieser Stelle im PDF oder DocBook generiert wird:

[index]
== Index

Ähnlich einfach ist das Anfertigen eines Literaturverzeichnis. Das Verzeichnis wird mit [bibliography] eingeleitet. Ein Eintrag, also etwa ein Buch mit Verlag, Erscheinungsjahr usw. erhält ein Label, das in dreifach eckige Klammern gepackt wird:

[bibliography]
[[[headfirst]]] Kathy Sierra & Bert Bates. Head First Java (A Brain Friendly Guide). OReilly and Associates. 2005.

Dort, wo im Text auf die Literaturquelle verwiesen werden soll, wird das Label in doppelte, spitze Klammern verpackt:

Meine Empfehlungen für den Einstieg in die Java-Programmierung sind Head First Java <<headfirst>> von Kathy Sierra und Bert Bates […].

In umfangreichen wissenschaftlichen Arbeiten werden die Literaturquellen gerne mit einer Software wie Citavi oder Zotero verwaltet. Über den BibTeX-Export können diese mächtigen Programme auch als Datenquelle für AsciiDoc-Dokumente genutzt werden. Weitere Informationen dazu findet man beim GitHub-Projekt asciidoctor-bibtex.

Konvertierung mit Asciidoctor

Um aus dem Rohtext nun ein PDF, eine Webseite oder gar ein Buch zu generieren, ist ein AsciiDoc-Konverter erforderlich. Dabei hat man die Wahl zwischen dem ursprünglichen, in Python geschrieben, AsciiDoc-Script, oder dem neueren Asciidoctor.

Asciidoctor ist eine in Ruby geschriebene Open-Source-Implementierung von AsciiDoc. Diese hat eine Reihe von Vorteilen, wobei vor allem die 25-fach schnellere Verarbeitung eine deutliche Verbesserung darstellt. Aber auch die Möglichkeit, AsciiDoc in Java oder Maven nutzen zu können, dürfte den einen oder anderen interessieren. Hier wird im folgenden Asciidoctor beschrieben.

Die Installation des Tools hängt vom verwendeten Betriebssystem ab und ist im Abschnitt Installation der Dokumentation beschrieben. In den meisten Fällen wird das mit gem, Rubys Paketsystem, erfolgen. Wenn Ruby installiert ist (lässt sich prüfen mit ruby --version), geschieht das mit folgendem Befehl, der gegebenenfalls mit Admin-Rechten ausgeführt werden muss:

gem install asciidoctor

Auf Debian- oder Ubuntu-Systemen kann man Asciidoctor dagegen einfach mit Hilfe des Paketmanagers apt installieren:

sudo apt-get install asciidoctor

Danach sollte die Eingabe von asciidoctor --version zu einer Ausgabe der Versionsnummer (und nicht zu einer Fehlermeldung) führen.

Asciidoctor enthält Prozessoren für eine Vielzahl an Ausgabeformaten:

  • html
  • docbook
  • manpage
  • pdf
  • latex
  • epub3

Für einige dieser Formate ist allerdings ein weiteres Gem erforderlich.

Die Verwendung ist denkbar einfach. Um beispielsweise ein HTML-Dokument aus einem Text zu machen, ist der folgende Befehl auszuführen:

asciidoctor text.adoc

Natürlich lässt sich das Ergebnis mit Hilfe eines eigenen CSS gestalten, man muss also nicht mit dem Standard-Output leben. Näheres dazu findet sich in der Dokumentation.

Um ein DocBook aus dem Text zu generieren, ist die folgende Eingabe erforderlich:

asciidoctor -b docbook text.adoc

Zum Erzeugen eines PDF aus dem gleichen Text wird das asciidoctor-pdf-Gem benötigt:

gem install asciidoctor-pdf

Die Konvertierung erfolgt dann mit dem folgenden Kommando:

asciidoctor-pdf text.adoc

Die Anweisungen zur Konvertierung in andere Formate funktionieren ähnlich und sind in der Dokumentation von Asciidoctor im Abschnitt Processing Your Content beschrieben.

Jedem seinen Editor

Da AsciiDoc zu den leichtgewichtigen Markupsprachen gehört, wird eigentlich kein besonderer Texteditor benötigt. Der Text lässt sich mit einem beliebigen Editor bearbeiten und nach der Fertigstellung in das gewünschte Format konvertieren. Empfehlenswert ist auf alle Fälle ein Editor mit Syntax-Highlighting, der die geschilderten Formatierungsansweisungen farblich hervorhebt. Das können eine ganze Menge Editoren, genannt seien TextMate für macOS, Notepad++ für Windows oder Vim und Emacs für Linux-Systeme. In der Praxis wird man außerdem dankbar für eine Vorschau auf das Endergebnis sein.

Ein großartiger Texteditor, der sowohl Syntax-Highlighting als auch Vorschau für AsciiDoc bietet und, darüber hinaus, gleich für alle genannten Plattformen verfügbar ist, ist Atom. Der Editor lässt sich mit Plugins erweitern und die Pluginsammlung asciidoctor enthält mehrere Werkzeuge, die die Arbeit mit AsciiDoc erleichtern. Auf dem folgenden Screenshot sind sowohl Syntax-Highlighting (links) als auch die Vorschau (rechts) erkennbar.

AsciiDoc-Syntax-Highlighting und -Preview in Atom

Atom ist kostenlos auf der Webseite des Projekts erhältlich.

Fazit

Für einfache Texte wie Blog-Posts oder diesen Beitrag ist Standard-Markdown vollkommen ausreichend und perfekt geeignet. Mit dem Dokumentkonverter Pandoc lässt sich auch Markdown in alle gängigen Formate überführen.

Wer aber vor einem größeren Projekt steht, einer Studienarbeit, einem Fachbuch oder einer komplexen technischen Dokumentation, sollte sich AsciiDoc auf jeden Fall anschauen. Dieser Beitrag hat nur einen kleinen Teil der Features von AsciiDoc vorgestellt, das Format ist ausgereift und bietet erstaunliche Möglichkeiten. Mit Atom und dem Plugin asciidoc-preview (Teil der asciidoctor-PluginSammlung) steht ein Editor zur Verfügung, der eine großartige Unterstützung für das Format bietet. Atom hat darüber hinaus eine gelungene Git-Integration, so dass die Arbeit auch gleich gesichert oder mit Co-Autoren geteilt werden kann.