Das Markdown-Format bietet die Möglichkeit, ohne verwirrende Tags einen Text zu erstellen, den Sie dann in verschiedenste Ausgabeformate konvertieren.

Einmal schreiben, überall veröffentlichen – die Idee von AsciiDoc [1] ist alt: aus einem in einem speziellen Format abgefassten Dokument über einen Konverter Varianten des Dokuments in unterschiedlichen Formaten zu erzeugen. Daran haben sich schon viele Entwickler versucht, meist mit eher mäßigem Erfolg.

Für das System spricht, dass etliche Entwickler aktiv an dem Projekt arbeiten und es weite Verbreitung genießt. Das schürt die Hoffnung, dass es im Wesentlichen so funktioniert, wie es die Dokumentation verspricht. Inzwischen nehmen sogar einige Verlage Quelltexte in diesem Format an oder nutzen es zumindest intern für ihre Zwecke. Der damit quasi industrielle Einsatz spricht ebenfalls für AsciiDoc.

Das System besteht aus dem Quelltext und einem Konverter, der Ersteren in die entsprechenden Ausgaben umwandelt. Die einzelnen Formate erzeugt die Software über sogenannte Backends. Die Tabelle “Ausgabe” zeigt, welche Backends AsciiDoc kennt und was sie erzeugen.

Das Designziel des Markups für die Quelltexte war ein für Menschen leicht verständliches Format, das dennoch relativ weitreichende Möglichkeiten mitbringt. Dazu gehört unter anderem, alle üblichen Auszeichnungen und Strukturen zu unterstützen, die heute im Alltag zum Einsatz kommen. Das schließt neben den hierarchischen Ebenen zum Gliedern eines Texts auch Verweise innerhalb des Dokuments sowie URLs auf externe Inhalte ein. Darüber hinaus ermöglicht die Software das Einbetten von Stichwörtern, Indizes und Fußnoten, literarischen Referenzen sowie Bildern und Tabellen.

Bei AsciiDoc orientierten sich die Entwickler an vielen der ohnehin schon weit verbreiteten Konventionen für Textdateien. Vieles kommt Ihnen vermutlich bekannt vor, da Sie es wahrscheinlich schon verwendet haben – etwa beim Unterstreichen einer Überschrift mit Istgleich-Zeichen oder dem Markieren eines Listenpunkts mit einem Sternchen am Zeilenanfang.

Absätze, das wohl wichtigste Element zum Gliedern eines Texts, erzeugen Sie durch eine Leerzeile. Beginnt der Fließtext eines Absatzes nicht in der ersten Spalte, also mit mindestens einem Leerzeichen oder Tabulator, behandelt AsciiDoc den gesamten Absatz besonders und übernimmt ihn wortwörtlich, ohne Interpretation der enthaltenen Formatierungen. Das schlägt sich in einer Schrift mit fester Laufweite bei der Ausgabe nieder.

AsciiDoc unterstützt zudem eine spezielle Form der Absatzformatierung: In der Zeile vor dem fraglichen Absatz darf eine Anweisung der Form [Typ] in einer ansonsten leeren Zeile stehen (Listing 1), wobei AsciiDoc zwischen vier solcher Typen unterscheidet (siehe Tabelle “Absatztypen”).

...
[listing]
Hier beginnt der grau unterlegte Absatz.
...

Mehrere aufeinanderfolgende Leerzeichen im Fließtext fasst AsciiDoc beim Konvertieren zusammen. Um an besonderen Stellen Leerraum fest einzufügen, benötigen Sie spezielle Zeichen (“non breakable spaces”), die Sie mit {nbsp} erzeugen – davon dürfen Sie mehrere hintereinander setzen. Klassische Auszeichnungen im Text bedienen sich der verbreiteten Markdown-Syntax (siehe Tabelle “Markdown in Kürze”).

Die zum Gliedern erforderlichen Ebenen erzeugen Sie bei Bedarf auf zwei Arten: entweder durch einzeilige Anweisungen oder durch eine Variante auf zwei Zeilen. Die sogenannten Singleline Header (siehe Tabelle “Ebenen”) erkennen die Konverter nur korrekt, wenn Sie diese tatsächlich in einer Zeile angeben – dafür dürfen die abschließenden Tags fehlen.

Alternativ unterstreichen Sie Überschriften mit unterschiedlichen, die Ebene der Gliederung kennzeichnenden Zeichen (Listing 2): für die erste Ebene mit Gleichheitszeichen, für die zweite mit Minuszeichen, bei der dritten mit Tilden, dann mit dem Caret und schließlich auf der untersten Ebene mit Pluszeichen.

Titel des Dokuments
=======Kapitel
-------Abschnitt
~~~~~~~Unterabschnitt
^^^^^^^Abschnitt des Unterabschnitts
+++++++

Das Beispiel der Gliederungsebenen zeigt einige der wesentlichen Features von AsciiDoc: So gibt sich das Format recht flexibel – etwa dadurch, dass es unterschiedliche Formatierungen im Quelltext zulässt. Das sorgt aber andererseits für eine gewisse Unklarheit. Ähnliches gilt ebenfalls für die Möglichkeit, abschließende Tags bei den einzeiligen Markierungen auszulassen: Das ist zwar komfortabel, erschwert es aber manchmal, Fehler zu finden, die das Konvertieren verhindern. Dieses Problem tritt beim Einsatz mehrzeiliger Tags ebenfalls auf: Diese verursachen in der Praxis erheblich mehr Probleme als ihre einzeiligen Pendants.

In der Zeile vor Überschriften dürfen Sie zusätzlich Anker setzen, sprich: ein Label für Verweise (Listing 3). Die ersten Zeilen eines Dokumentes reserviert AsciiDoc für besondere Aufgaben: Neben dem Titel des Dokuments geben Sie dort optional den Namen des Autors, eine Mailadresse und eine Revisionsnummer samt Datum ein. Diese Angaben verwendet die Software sowohl für die Metadaten des Dokuments wie auch in der Ausgabe als lesbare Information.

[Label]
=== Überschrift des Abschnitts

Verweise und Links

Bei Verweisen innerhalb eines Dokumentes erzeugt [[Label]] den Anker, auf den Sie an beliebiger Stelle im Text mit <<Label>> oder <<Label,Text>> verweisen. Obwohl AsciiDoc laut Beschreibung voll auf Unicode setzt, führen Sonderzeichen im Label zu Problemen beim Konvertieren. Der oben erwähnte Text für den Verweis entschärft die Situation etwas: Die Software setzt ihn an den Stellen ein, an denen der Verweis im Fließtext steht, und erlaubt darin beliebige Zeichen.

Fehlt der Verweistext, setzt AsciiDoc beim Konvertieren stattdessen das zuvor definierte Label oder ein anderes Element ein. Die Regeln dafür, was die Software dazu verwendet, gestalten sich vielfältig: Bei Abschnitten etwa kommt der Text der Überschrift zum Einsatz.

Auf andere Dokumente verweisen Sie in einer der in den ersten beiden Zeilen von Listing 4 gezeigten Formen. Pfade geben Sie, falls erforderlich, zusammen mit dem Dateinamen an. Für URLs nutzen Sie eine einfache Syntax (Listing 4, Zeile 3 und 4). Beides erkennt das Programm automatisch an dem Schlüsselwort http:. Das Gleiche gilt für Mailadressen (Zeile 5 und 6).

link:Dateiname#ID
link:Dateiname#ID[Text]
http://Adresse
http://Adresse[Text]
mailto:Adresse
mailto:Adresse[Text]

Bilder kann AsciiDoc auf zwei unterschiedliche Arten einbinden: Im Fließtext als “inline graphics” oder als eigenen Block, quasi als Bild-Absatz. Das Schlüsselwort images: kommt für Bilder im Fließtext zum Einsatz:

images:Dateiname[Text]

Selbst wenn ein Text fehlt, müssen Sie die eckigen Klammern immer angeben. Tatsächlich darf der Text zum Beschriften zusätzliche Formatierungen für das Bild enthalten, beispielsweise eine Größenangabe in der Form height=14pt.

Setzen Sie die Grafiken in einen eigenen Absatz, dann besteht der erste Teil des Schlüsselworts aus images, gefolgt von zwei Doppelpunkten. Danach tragen Sie den Dateinamen ein (optional mit Pfad) gefolgt von den eckigen Klammern. In diese dürfen Sie einen Text eintragen, zwischen doppelten Hochkommas nach dem Schlüsselwort caption=. Alternativ – und übersichtlicher – ist aber die in Listing 5 verwendete Form, die zusätzlich noch ein Label für die Grafik definiert.

[[Label]]
.Text
images::Dateiname[Optionen]

Listen gehören zu den Elementen, die sich mit AsciiDoc wirklich gut formatieren lassen. Besonders einfach geht das mit Aufzählungen, die Spiegelstriche verwenden: Hier leiten Sie die Zeile mit einem Minuszeichen oder einem Sternchen ein. Erhöhen Sie die Anzahl der führenden Zeichen, erhöhen Sie zugleich die Tiefe der Ebene.

Nach einem ähnlichen System gestalten Sie nummerierte Listen. Dabei schaltet AsciiDoc in jeder Ebene die Art des Nummerierens um (Listing 6). Noch eleganter klappt das mit der Punkt-Form: Stellen Sie der Zeile einen bis maximal fünf Punkte voran, so entstehen im Ergebnis nummerierte Listen nach den oben genannten Kriterien.

1. Dezimalzahlen
a. Kleinbuchstaben
F. Großbuchstaben
iii) kleine römische Zahlen
IX) große römische Zahlen

Sie dürfen die Typen der Listen mischen und verschachteln, müssen dann aber sehr genau auf Leerzeilen achten, damit AsciiDoc erkennt, welche Elemente zusammengehören und wo eine Liste endet. Da dies erfahrungsgemäß oft zu Schwierigkeiten führt, hilft es, zunächst die Listen in einer separaten Datei zu speichern und testweise zu übersetzen. Funktioniert alles, fügen Sie den Code in das Dokument ein.

Um ein weiteres Strukturelement handelt es sich bei den sogenannten Delimited Blocks, Strukturen, die bestimmte Formatierungen verwenden, wie bei der Anzeige von Quelltexten. Im LaTeX-Jargon hießen diese “Umgebungen”. Zunächst definieren Sie zwischen den eckigen Klammern die Variante der Umgebung, dann folgt durch eine Reihe von speziellen Trennzeichen der Anfang der Umgebung. Normalerweise gibt es mehrere Varianten jeder dieser Umgebungen, die allerdings nicht bei allen Formaten gleichermaßen bereitstehen oder unterschiedlich erscheinen. Listing 7 zeigt die grundlegende Strukturen.

///////////////////Kommentar
///////////////////
-------------------Listing
-------------------
...................Verbatim-Text
...................
*******************Eingerahmter Text
*******************
___________________Zitat (eingerückt)
___________________
+++++++++++++++++++Durchgereichter Code
+++++++++++++++++++

Alle Blöcke beginnen zwingend am Zeilenanfang einer ansonsten leeren Zeile. Sie bestehen aus einer Reihe spezieller Zeichen, wie Sternchen, Minuszeichen oder Ähnliches. Bis eine identische Zeile auftritt, dürfen Sie nun den gewünschten Code eingeben.

In der Zeile vor der den Block einleitenden Zeile legen Sie die Variante, den sogenannten “Style”, der Umgebung fest. Das funktioniert allerdings nicht immer; viele der eigentlich vorgesehenen Styles harmonieren nicht mit allen Ausgabeformaten, sondern führen beim Übersetzen zum Abbruch.

Die in Listing 8 gezeigte Open-Block-Struktur beginnt und endet mit zwei Minuszeichen. Sie dient in der Variante abstract für Zusammenfassungen, als partintro nimmt sie die einleitenden Texte für Teile eines Buchs (“Parts”) auf. Zudem erlaubt sie das Fortsetzen von Listen [2].

[Variante]
--Code
--

Das AsciiDoc-Tabellenformat liefert für einfache, kurze Inhalte recht gute Ergebnisse. Listing 9 zeigt den Quelltext für eine simple Tabelle. Alle wesentlichen Einstellungen erfolgen über Optionen, die zwischen den eckigen Klammern vor der Tabelle stehen. Die Tabelle selbst erstellen Sie durch Pipe- und Gleichheitszeichen. Bei kurzen Inhalten stellt das kein Problem dar; bei komplexeren Tabellen steigt die Fehlerrate in der Praxis schnell an.

.Tabellenüberschrift
[width="66%",cols="<m,a",frame="all",options="header"]
|======================
|Spaltenüberschrift 1 |Spaltenüberschrift 2
|1        |Item 1
|2        |Item 2
|3        |Ein sehr langer Eintrag, der nicht mehr in eine Zeile passt und automatisch umbrochen wird.
|======================

Die Tabellenoptionen gliedern sich in mehrere Gruppen (siehe Tabelle “Zeilen und Spalten”). Bei AsciiDoc dürfen Tabellen immer eine Kopfzeile – üblicherweise für die Bezeichner der Spalten – und eine Fußzeile umfassen. Beide erhalten spezielle Formate, sofern Sie dieses durch die Schlüsselworte header beziehungsweise footer aktivieren.

Die Angabe eines Stils für die Spalten verursacht eine Reihe von Nebenwirkungen, wie Sie am Beispiel aus Listing 11 ausprobieren können, indem Sie das Format für die Spalten von a auf v umstellen. Wirklich unübersichtlich gestaltet sich der Einsatz von Formatierungen für die Zellen; Abbildung 1 zeigt ein abschreckendes Beispiel.

Abbildung 1: AsciiDoc erlaubt zwar weitgehende Formatierungen in Tabellen, aber der Quelltext verliert dann zunehmend an Klarheit.

Probleme

Fehler beim Abfassen von AsciiDoc-Dokumenten treten naturgemäß erst beim Übersetzen zutage. Einige Editoren, darunter wie Emacs, unterstützen die Eingabe entsprechender Quelltexte durch spezielle Modi, die zumindest einige einfache Flüchtigkeitsfehler bereits beim Schreiben aufdecken. Komplexere logische oder gar Syntaxfehler finden diese Helfer freilich nicht.

Die AsciiDoc-Dokumentation [3] fällt recht dürftig aus, sodass es sinnvoll ist, die wenigen Beispiele zur Hand zu haben, wenn es an das erste eigene Projekt geht. Einige der Dokumente finden sich auf der Website, darunter ein Artikel, der den Einsatz von Indexen zeigt [4], eine als Artikel formatierte Variante des User Guides [5] sowie eine Vorlage für ein Buch [6], das komplexere Strukturen wie eine Literaturliste, ein Kolophon und eine Widmung vorstellt.

Das Übersetzen mit dem AsciiDoc-Skript in der Form asciidoc OptionenQuelltext sowie der Einsatz der A2x-Toolchain benötigen erstaunlich viel Zeit, um aus relativ einfachen Quelltexten EPUBs oder PDFs zu generieren. Über die Option -v erhalten Sie detailliertere Informationen zum Vorgang.

Bei der reinen Text- oder HTML-Ausgabe sieht es etwas besser aus: Allerdings unterstützen diese Formate nur eine Teilmenge der Möglichkeiten, sodass sie sich bestenfalls für eine Vorschau der Dokumente eignen.

Um den Zeitaufwand zu minimieren, hat sich der Einsatz des Shell-Operators && bewährt: Darüber verknüpfen Sie das Erzeugen einer HTML-Datei mit dem eines aufwendigeren Formats. Die syntaktischen Fehler finden und beheben Sie dann bei der schnelleren HTML-Konvertierung, und nur wenn diese erfolgreich verläuft, erfolgt das Umwandeln in die anderen Formate.

Allerdings garantiert ein erfolgreiches Konvertieren nach HTML noch lange nicht, dass eine PDF-Datei das gewünschte Ergebnis zeigt. Gerade die Ausgabe für den Druck ist eine echte Schwachstelle von AsciiDoc (Abbildung 2). Tatsächlich fällt es relativ schwer, direkt mit AsciiDoc gut gesetzte PDFs zu erzeugen: Hier bietet sich der Zwischenschritt über den LaTeX-Export als Mittel der Wahl an. AsciiDoc erzeugt Standard-LaTeX, das Sie dann nach dem manuellen Bearbeiten in einem weiteren Schritt in ein PDF-Dokument übersetzen.

Abbildung 2: Selbst Dokumente, die sowohl mittels Dblatex als auch mit FOP funktionieren, zeigen bei der PDF-Ausgabe gravierende Unterschiede.

Der Vorteil der zweiten Methode liegt vor allem darin, dass Ihnen dabei alle Möglichkeiten von LaTeX offenstehen, der Aufwand sich jedoch in engen Grenzen hält. AsciiDoc unterstützt aber nur eine kleine Teilmenge der in LaTeX vorhandenen Formate; unter anderem keine Picture-Umgebungen, was deren Einsatz entweder ausschließt oder Sie dazu zwingt, diese nachzureichen.

Konvertieren

Das Übersetzen – sprich: Konvertieren – des Quelltexts in das gewünschte Zielformat erledigen Sie mit einer Befehlszeile in der folgenden Form:

$ asciidoc Optionen Quelltext

Als wichtigste Option definiert dabei -b das Format der Ausgabe. Bei Formaten wie PDF oder EPUB benötigt AsciiDoc allerdings eine ganze Toolchain, um das gewünschte Resultat zu generieren. Als Wrapper dafür bringt die Standardinstallation von AsciiDoc das Python-Script a2x mit. Es verwendet eine zu asciidoc weitgehend inkompatible Syntax und benötigt viele zusätzliche Tools, beispielsweise Epubcheck oder die Docbook-Utilitys.

Alternativ steht ein Ruby-Skript mit dem Namen asciidoctor bereit, das nochmals wesentlich erweiterte Funktionen mitbringt. Es verhält sich allerdings wiederum in vielen Bereichen inkompatibel sowohl zum Kommando asciidoc wie auch zu a2x.

Da sich AsciiDoctor [7] oft nicht in den Repositories gängiger Distributionen befindet, bleibt hier nur die manuelle Installation. Sie gelingt zwar ohne Probleme, erfolgt aber voreingestellt nur für den aktuellen Anwender. Der Code befindet sich als Gem auf RubyGems.org. Sie installieren ihn mit folgendem Aufruf:

$ gem install asciidoctor

Dies setzt eine vorhandene Ruby-Installation voraus und zieht auch noch JRuby, die Java-Variante von Ruby, sowie eine Vielzahl spezieller Fonts nach. Hat alles funktioniert übersetzen Sie anschließend AsciiDoc-Dateien mit dem simplen Aufruf asciidoctor Dateiname.

A2x

In vielen Fällen erweist sich aber A2x als die einfachere und ausreichend leistungsfähige Möglichkeit, aus AsciiDoc andere Formate zu generieren. Dieses Tool kann alle in der Tabelle “Formate A2x” angegebenen Formate erzeugen. Hier heißt die Option -f, das Argument legt das Format fest.

A2x unterstützt neben diversen HTML-basierten Formaten auch EPUB und Docbook-basierte Formate wie PDF, PS und DVI. Mit gewissen Einschränkungen erzeugen Sie mit dem Tool LaTeX-Quelltexte sowie reine Textdateien.

Bei den Formaten PDF und PS, nicht aber beim inzwischen völlig veralteten DVI, setzt A2x zwei unterschiedliche Verfahren ein. Voreingestellt verwendet es Dblatex (“Docbook-LaTeX”), das oft Fehler produziert, die das Übersetzen verhindern. Da die Fehlermeldungen oft wenig aussagekräftig ausfallen, gestaltet sich die Suche nach der Ursache häufig langwierig. Daher ist der Apache Formatting Objects Processor FOP [8] oft die bessere Wahl.

A2x erzeugt neben PDF auf Wunsch auch SVG und diverse Bitmap-Formate. Als wesentliche Eigenschaft in diesem Kontext gefällt die Robustheit. Mit der Option --fop erzeugte PDFs gelingen deutlich einfacher als die mit Dblatex generierten, wenn sie auch typografisch nicht sehr schön ausfallen.

Die Option -k verhindert, dass A2x die temporären Dateien löscht. Von diesen interessiert fürs Debugging insbesondere die Eingabedatei.xml. Der beim Übersetzen automatisch aufgerufene XML-Checker Xmllint liefert im Idealfall eine Fehlermeldung wie in Listing 10: Dort steht dann die Zeile der XML-Datei, in der das Tool einen Fehler entdeckt hat.

a2x: executing: "xmllint" --nonet --noout --valid "tst.xml"
tst.xml:2113: element section: validity error : Element section content does not follow the DTD, expecting ..., got (title )
</section>
          ^

Wie schon bei LaTeX muss es nicht zwingend die angegebene Zeile sein, die den Fehler enthält. Die Angabe hilft aber, das Problem einzukreisen. Was wirklich schiefgegangen ist, verrät die Fehlermeldung noch weniger als bei LaTeX – allerdings kommen Sie mit etwas Übung dahinter.

Wenn Sie das Überprüfen mittels Xmllint deaktivieren (-L), beschleunigt das zwar das Übersetzen etwas, führt aber dazu, dass Sie Fehler kaum noch finden. Die Tabelle “A2x-Optionen” gibt Aufschluss über die weiteren Funktionen der Software.

Eine Besonderheit von A2x verdient noch Beachtung: Das Tool ist in der Lage, zu Beginn eines Quelltextes stehende Kommentare auszuwerten und daraus weitere Optionen zum Konvertieren abzuleiten. Die Dokumentation beschreibt das Verfahren, anhand des Beispiels, was zu tun ist, wenn es nicht gelingt, das Nummerieren von Abschnitten mittels :numbered!: zu deaktivieren [9]. Tatsächlich erledigen die drei letzten in Listing 11 gezeigten Zeilen den Job.

// a2x default options.
//    a2x: -f epub -d book --epubcheck
// Suppress revision history in dblatex outputs.
//    a2x: --dblatex-opts "-P latex.output.revhistory=0"
// Suppress book part, chapter and section numbering in DocBook XSL outputs.
//    a2x: --xsltproc-opts
//    a2x: "--stringparam part.autolabel 0
//    a2x: --stringparam chapter.autolabel 0
//    a2x: --stringparam section.autolabel.max.depth 0"

Fazit

AsciiDoc hinterlässt einen zwiespältigen Eindruck. Zwar gestaltet sich die Syntax im Prinzip sehr einfach, aber das geht auf Kosten der Zuverlässigkeit. Bei komplexen Strukturen wie ineinander verschachtelten Elementen oder dem Einsatz von Quellcode als Teil des Texts sind Probleme vorprogrammiert. Oft fällt es obendrein schwer, diese einzukreisen.

Weder in Sachen Geschwindigkeit noch beim Behandeln der Fehler haben die Entwickler aus den jahrzehntelangen Erfahrungen mit LaTeX gelernt: In beiden Aspekten bietet AsciiDoc keine wesentlichen Vorteile. Was Erweiterbarkeit und Qualität der (PDF-)Ausgaben angeht, liegt LaTeX sogar um Längen vorn. Allerdings ändert sich das, wenn es um HTML-basierte Formate wie EPUB geht: Dafür eignet sich AsciiDoc besser – es sei denn, Sie benötigen ein Feature, das die Entwicklern so nicht vorgesehen haben.

Dem gegenüber steht das einfache, mit einem Editor umsetzbare Format, das immer noch in den meisten Fällen halbwegs leserlich erscheint. Allerdings schwindet die Lesbarkeit bei zunehmender Komplexität der Quelltexte recht schnell.