Asciidoctor - Werkzeug zur Erstellung von technischen Dokumenten

Kein Entwickler / kein Administrator erstellt gerne Dokumentation. Auch ich kann mir angenehmere Tätigkeiten vorstellen. Allerdings habe ich mich auch schon oft geärgert, bestimmte Dinge nicht dokumentiert zu haben. Durch dem Einsatz von Asciidoctor könnte das Erstellen von technischen Dokumenten aber doch noch Spaß machen.

Was ist AsciiDoctor?

Asciidoctor ist die Ruby-Implementierung des ursprünglich in Python geschriebenen Asciidoc. Das Programm dient zur Übersetzung von in der Auszeichnungssprache AsciiDoc erstellten Dokumenten. AsciiDoc ist eine leichtgewichtige Auszeichnungssprache. Ähnliche Sprachen kennt man von Github (Markdown) oder der Wikipedia (Wikitext).

Im Vergleich zu Markdown bietet AsciiDoc wesentlich umfangreichere Möglichkeiten zur Formatierung des Textes. Die Auszeichnungen von AsciiDoc sind umfangreicher und beinhaltet viele in der Grundversion von Markdown vermisste Elemente.

Ziel dieser Sprachen ist es, den Text bereits in einer lesbaren Version zu erstellen. So lassen sich alle Texte, die mit AsciiDoc ausgezeichnet sind auch ohne Übersetzung in einem Editor lesen. Weiterhin haben Auszeichnungssprachen den Vorteil, den Autor bei der Erstellung nicht aus dem Schreibfluss zu bringen. Es ist nicht mehr notwendig zur Formatierung des Textes zur Maus zu greifen oder sich mit den Unzulänglichkeiten seines Programms auseinander zusetzen. Ein einfacher Texteditor reicht aus. Die wichtigsten Auszeichnungen hat man schnell gelernt. Man kann sich wieder auf den Text konzentrieren.

Wie erstelle ich ein Dokument mit AsciiDoc?

Zur Erstellung eines Dokuments mit AsciiDoc Auszeichnung benötigt man nur einen Editor. Es gibt für viele Editoren Erweiterungen, die die Syntax von AsciiDoc unterstützen. Unter Windows ist das der Editor Notepad++ sowie unter Linux gEdit. Für beide stehen in Github entsprechende Erweiterungen zur Verfügung.

Ansonsten beginnt man einfach zu schreiben. Absätze werden in AsciiDoc durch eine Leerzeile getrennt. Überschriften Beginnen mit einem = Zeichen. Je nach Ebene der Überschrift werden weitere = Zeichen angehängt.

Möchte man Wörter besonders hervorheben, verwendet man das * um eine Wort fett darzustellen. Der Unterstrich formatiert das Wort kursiv. Wichtig für technische Dokumentationen ist das + Zeichen. Mit diesem wird der darin eingeschlossene Text mit einer nicht proportionalen Schriftart gesetzt.

Ein kurzer Beispieltext könnte z.B. wie folgt aussehen:

= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An *introduction* to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
----
puts "Hello, World!"
----

In obigem Text ist auch ein Beispiel für Blöcke enthalten. Durch Sie wird z.B. Quellcode zur Programmiersprache passend formatiert. Blöcke können aber auch durch Erweiterungen zur Verfügung gestellt werden.

Einen Überblick über die Möglichkeiten von AsciiDoc erhält man durch den AsciiDoc Writer’s Guide oder die AsciiDoc Syntax Quick Reference.

Wie und in welche Formate kann ich AsciiDoc rendern?

Mit einem einfachen Aufruf lässt sich das erstellte Dokument im AsciiDoc Format in eine HTML-Seite "übersetzen".

asciidoctor document.adoc

Als Ergebnis erhält man eine HTML-Datei, die keine weiteren Dateien benötigt. Man kann diese Datei direkt mit dem Browser öffnen oder mit entsprechenden Web-Servern veröffentlichen.

Durch den Aufruf von asciidoctor mit einem anderen Backend kann das Dokument in das DocBook Format übersetzt werden.

asciidoctor -b docbook5 document.adoc

Ausgehend vom DocBook Format kann dann jedes weitere Format erzeugt werden. Bereits mit entsprechenden Tools der Asciidoctor Entwickler selbst unterstützt wird PDF.

Was geht noch?

Bereits mit den bisher beschriebenen Möglichkeiten kann mehr sehr einfach ansprechende Dokumente erstellen. Ich selbst habe bei der Nutzung von Asciidoctor festgestellt, dass das Erstellen von Dokumentation damit wesentlich mehr Spaß macht. Vorbei sind die Zeiten, da ich mich von der Textverarbeitung im Schreibfluss unterbrechen lassen musste. Auch fällt der Wechsel zwischen Entwicklungssystem und Textverarbeitung weg.

Der große Vorteil ist, dass AsciiDoc Dokumente wie normaler Quellcode behandelt werden. Sie werden in die Quellcodeverwaltung (Subversion, Git) eingecheckt. Sie können zusammen mit dem Quellcode versioniert werden. Über die Quellcodeverwaltung ist auch ein gemeinsames Arbeiten an ein und demselben Dokument möglich.

Asciidoctor kann in vielen Programmen eingesetzt werden. So stehen Plugins für Maven und Gradle zur Verfügung. Damit können Dokumente mit AsciiDoc Auszeichnung im Build in HTML oder ein andere Format übersetzt werden. Die Maven-Erweiterung bietet auch die Möglichkeit die Seiten der Maven-Site in AsciiDoc zu erstellen.

Eine weitere Möglichkeit ist der Einsatz von AsciiDoclet. Damit wird der HTML-Syntax bei der Erstellung von Kommentaren in Javadoc durch AsciiDoc ersetzt.

Eine interessante Erweiterung für Asciidoctor selbst ist asciidoctor-diagram. Damit können Diagramme, die ebenfalls in einer Textbeschreibung vorliegen, in das Dokument (als Block) integriert werden. Von der Erweiterung werden derzeit die folgenden “Grafik Formate” unterstützt:

• Graphviz

• PlantUML

• ditaa

Wo wird AsciiDoctor / AsciiDoc eingesetzt?

AsciiDoc ist nicht neu. Es wird bereits seit längerer Zeit von RedHat zur Erstellung der Dokumentation für OpenSource-Produkte eingesetzt. Das ist nicht weiter verwunderlich, ist einer der Haupt-Maintainer von Asciidoctor doch ehemaliger RedHat-Angestellter.

In Deutschland wird das AsciiDoc Format von Open Source Press Verlag verwendet. Die Autoren erstellen das Manuskript in AsciiDoc. Über einen selbst entwickelten Prozess kann der Verlag daraus sowohl die Vorlagen für den Druck des Buches als auch verschiedene elektronische Format erzeugen. AsciiDoc löst bei Open Press das bisher verwendete System basierenden auf LaTeX ab. Weitere Informationen hierzu sind den beiden Blog-Beiträgen zu entnehmen: Bye-bye LaTeX!, AsciiDoc.

Dokumentieren kann Spaß machen!

Ich hätte nicht gedacht, dass mir das Erstellen von technischen Dokumenten einmal Spaß machen könnte. Mit AsciiDoc funktioniert das aber. Ich kann mich endlich auf den Text konzentrieren und werde nicht durch nervende Textverarbeitungsprogramme abgelenkt.