Ein Dokument, viele Ausgabeformate – das klingt verlockend und klappt in der Praxis ganz gut. Kleine Stolperfallen bleiben aber bestehen.

Über die letzten Jahrzehnte haben sich verschiedene Ansätze herausgebildet, um Textdokumente zu erstellen und zu pflegen. Dabei setzen Bürosuiten wie LibreOffice und Microsoft Office auf eine komprimierte XML-Datei als Format. Eine grafische Benutzeroberfläche verbirgt dabei die Anweisungen zum Formatieren des Texts sowie das Umwandeln nach PDF oder HTML vollständig vor dem Benutzer.

Im Gegensatz dazu stehen Satzsysteme wie LaTeX und Markup-Sprachen wie Docbook [1], Markdown [2] und Asciidoc [3]. LaTeX entstand mit Blick auf den Satz von Büchern. Es erlaubt daher das Formatieren des Texts über Anweisungen im Dokument bis auf den letzten Picometer genau. Docbook setzt dagegen auf die Kombination aus XML und Stilvorlagen in Form von Cascading Style Sheets (CSS) und der Extensible Stylesheet Language (XSL).

Markdown, Asciidoc und Asciidoctor [4] sowie Asciidoctor-pdf [5] versuchen, das Schreiben der Texte radikal zu vereinfachen, zumindest in Bezug auf das Markup. Aus der Struktur und minimalen Elementen leiten sie ab, ob es sich beim Textteil um eine Überschrift oder etwa einen Punkt einer Aufzählung handelt. Das endgültige Aussehen des Dokuments bestimmen Sie über Stilvorlagen in Form von CSS oder YAML.

Pdflatex sowie die beiden Formate Markdown [6] und Asciidoc standen bereits in früheren Ausgaben im Mittelpunkt [7]. Alle drei haben gemeinsam, dass das Umwandeln ins endgültige Format mit mehreren Werkzeugen erfolgt, die im Verbund agieren. Aus dem ursprünglichen Text entsteht dann wahlweise PDF, HTML, Postscript, Manpages oder ganze E-Books. Im Linux-Werkzeugkasten finden Sie dafür Pdflatex, Latex2man, Dblatex, Xsltproc, Pandoc [8], Asciidoc, A2x [9], Asciidoctor und Asciidoctor-pdf.

Familienclan

Asciidoc erzeugt mithilfe verschiedener Skripte die Formate HTML, LaTeX, Docbook, Manpage oder eine Ausgabe für das CMS WordPress. Zu Asciidoc gehört das Universal-Tool A2x. Dieses Python-Skript ergänzt die Liste der Formate für die Ausgabe noch um Postscript, PDF und EPUB.

Asciidoctor ist das Ruby-Pendant zu Asciidoc. Über zusätzliche Module – im Ruby-Slang Gems genannt – stehen Skripte für PDF und EPUB3 bereit. Bei Asciidoctor-pdf handelt es sich um einen Asciidoctor-Fork mit Fokus auf PDF.

Bei der Installation der Tools gilt es, zahlreiche Abhängigkeiten aufzulösen – etwa zu LaTeX, XML, XSLT, Docbook, Python, Ruby, Javascript und Java. Unter Umständen rauschen dabei bis zu 800 MByte an zusätzlicher Software über die Leitung. Zudem finden sich nicht alle Komponenten komplett in den Repositories aller Distributionen, Sie müssen also etwas Handarbeit einplanen.

Die Dokumentation dazu ist ein wenig verstreut, weist mitunter Lücken auf, macht Sprünge und verlangt neben etwas Vorwissen und guten Kenntnissen in Englisch auch Freude am Experimentieren. Nichtsdestoweniger funktionieren die Werkzeuge an sich ausgezeichnet und haben sich in der Praxis bewährt. Dem Autor erleichtern sie regelmäßig das Erstellen und die Pflege von Büchern, Dokumentation und Schulungsmaterial.

Stellschrauben

Alle Clanmitglieder unterscheiden sich in den Parametern für den Aufruf und bei den Voreinstellungen zum Gestalten der Ausgabe (Stilvorlagen und Themes). Entweder benennen Sie die Stilvorlage im Asciidoc-Dokument selbst oder geben sie als Parameter beim Aufruf zum Übersetzen ins gewünschte Format an.

Mit den beigefügten Stilvorlagen von Asciidoc (Abbildung 1) erzeugen Sie auf Anhieb ansprechende und insbesondere leicht zu erfassende Dokumente und Folien. Asciidoctor sammelt seine Stilvorlagen in der Stylesheet Factory [10].

Abbildung 1: Über ein Ausklappmenü wählen Sie aus, mit welcher Stilvorlage der Asciidoctor ein Dokument ausstattet.

Die grundlegenden Einstellungen von Asciidoc finden Sie auf einem Linux-System mit Ubuntu oder Debian in der Datei /etc/asciidoc/asciidoc.conf. Die Stilvorlagen für die Ausgabe nach HTML in Form von Cascading Style Sheets (CSS) liegen hingegen unter /etc/asciidoc/stylesheets/. Die CSS-Dateien sind nach Ländern spezifisch angepasst, etwa bezüglich des Formats der Seiten und der Ränder.

Zusätzlich verfügt Asciidoc in Form von Themes noch über weitere Möglichkeiten zum Konfigurieren. Die Pakete enthalten unter /etc/asciidoc/themes/ zwei Zusammenstellungen namens flask und volnitsky. Mit den darin enthaltenen CSS- und Javascript-Dateien steuern Sie unter anderem die Farben für Überschriften, die Zeilen von Tabellen und horizontale Linien in den Kopf- und Fußzeilen eines erzeugten Dokuments. Jedes Theme liegt vollständig in einem gleichnamigen Verzeichnis, damit Asciidoc es findet und akzeptiert.

Asciidoctor hingegen verwendet eine etwas moderner ausgerichtete und recht elegant wirkende Stilvorlage, die Sie in der Datei /usr/share/asciidoctor/stylesheets/asciidoctor-default.css finden. Abbildung 2 zeigt, wie ein damit erstelltes Dokument im Webbrowser aussieht.

Abbildung 2: Mit dem Asciidoctor geben Sie dem übersetzten Dokument selbst mit dem Standardlayout ein etwas moderneres Aussehen.

Von Asciidoc nach HTML

Der einfachste Weg zum Festlegen eines Stils ist die Angabe im Header der Asciidoc-Datei. Das mitgelieferte Theme namens flask binden Sie über die zusätzliche Zeile :theme: flask ein.

Zum Übersetzen der Datei nach HTML genügt der Aufruf aus der ersten Zeile von Listing 1. Als Ergebnis erhalten Sie eine einzige HTML-Datei samt der Stilvorlage im Header. Wenn Sie das Asciidoc-Dokument nicht verändern dürfen oder einfach nur mit den Stilvorlagen experimentieren möchten, geben Sie den Namen des Themes als Parameter beim Aufruf an.

$ asciidoc document.adoc
$ asciidoc -b html --attribute theme=flask document.adoc
$ asciidoc -b html -a theme=flask document.adoc
$ asciidoc -b html -theme flask document.adoc

Die Zeilen 2 bis 4 von Listing 1 zeigen zwei längere und eine kürzere Versionen des Aufrufs. Der Schalter -b bezeichnet das ausgewählte Backend – hier HTML. Über --attribute theme beziehungsweise die beiden Kurzfassungen -a theme und -theme benennen Sie das Theme für das Rendering der Ausgabe.

Alle drei bisherigen Aufrufe nutzen die Datei /etc/asciidoc/themes/flask/flask.css als Stilvorlage. Liegt die Vorlage hingegen woanders, kommt die Option :themedir: ins Spiel. Für diese Option existiert kein entsprechender Kommandozeilenparameter, daher ergänzen Sie sie im Header des Dokuments.

Mit der Angabe :themedir: /opt/themes/demo erwartet Asciidoc die Stilvorlage demo.css im Verzeichnis /opt/themes/demo/ – der Name des Verzeichnisses und der Stilvorlage sollten übereinstimmen. Abbildung 3 stellt die Anwendung zweier Stilvorlagen auf dasselbe Dokument gegenüber.

Abbildung 3: Angewendete Stilvorlagen: Links sehen Sie ein leicht modifiziertes Theme flask, rechts das mitgelieferte Theme volnitsky.

Asciidoctor nach HTML

Wie bereits erwähnt, verwendet Asciidoctor seine eigene Stilvorlage. Der Aufruf zum Übersetzen nach HTML ähnelt jenem bei Asciidoc. Geben Sie keine weiteren Parameter an, kommt die Standardvorlage zum Einsatz (Listing 2).

$ asciidoctor document.adoc
$ asciidoctor -a linkcss document.adoc
$ ls
asciidoctor.css document.adoc document.html

Wie Asciidoc integriert auch Asciidoctor die verwendete CSS-Stilvorlage direkt in den Header der erzeugten HTML-Datei. Das stellt sicher, dass einerseits das HTML-Dokument in jedem Webbrowser möglichst gleich aussieht (Abbildung 1) und der Browser die Seite schneller lädt.

Benötigen Sie beide Dateien separat, erreichen Sie das entweder über den Parameter -a linkcss im Aufruf (Listing 2, Zeile 2) oder ergänzen die Angabe :linkcss: im Header der Datei mit dem Ausgangstext.

Asciidoctor erlaubt daneben die Angabe eines Pfads zur Vorlage, wiederum entweder fest im Header des Dokuments oder beim Aufruf über die Kommandozeile. Im Header versteht es die beiden Angaben :stylesdir: und :stylesheet: (Listing 3), im Aufruf zwei analoge Parameter (Listing 4). Sie dürfen sowohl absolute als auch relative Pfade verwenden; in den beiden Listings kommen Letztere zum Einsatz. Im Bedarfsfall behalten Sie über den Parameter linkcss die Trennung von Inhalt und CSS bei.

:stylesdir: theme/
:stylesheet: fun.css

$ asciidoctor -a stylesdir=theme/ -a stylesheet=fun.css document.adoc

Asciidoc nach PDF

Das Übersetzen von Asciidoc nach PDF erfolgt mittels A2x. Dazu stehen Ihnen zwei ausgefeilte Backends bereit: Dblatex [11] und der Apache Formatting Objects Processor FOP [12]. Beide vereinfachen den Prozess, nutzen dafür jedoch mächtigere Partner – entweder das Schwergewicht Docbook/LaTeX oder Java. Haben Sie diese bisher noch nicht installiert, halten Sie dafür ausreichend Speicherplatz und RAM bereit.

Dblatex verwendet bewährte Werkzeuge aus Docbook über LaTeX nach PDF. Zum eigenen Gestalten passen Sie die LaTeX-Stilvorlage für Dblatex an. Sie heißt asciidoc-dblatex.sty und findet sich unter /etc/asciidoc/dblatex/ im Dateisystem.

Verfügen Sie über fundierte LaTeX-Kenntnisse, helfen diese hier weiter. Die Bezeichnungen und Werte der Parameter für die Ausgabe sind vielfach identisch mit jenen bei LaTeX. A2x erlaubt ebenfalls die Angabe einer alternativen Stilvorlage als XSL. Dazu nutzen Sie im Aufruf den Schalter --xsl-file=datei.xsl.

Einen einfachen Aufruf zum Transformieren nach PDF zeigt die erste Zeile von Listing 5. Beachten Sie hier die explizite Angabe des Backends mittels -f pdf, das dann Dblatex benutzt.

$ a2x -f pdf document.adoc
$ a2x -f pdf --dblatex-opts "Option" document.adoc
$ a2x --fop document.adoc

Abbildung 4 zeigt das Titelblatt und die Revisionshistorie des erzeugten PDFs. Darauf folgen ein Inhaltsverzeichnis sowie der eigentliche Inhalt. Das erzeugte Dokument fällt dadurch mitunter sehr umfangreich aus. Bei Bedarf nehmen Sie die Elemente heraus, die Sie nicht benötigen. Dazu geben Sie im Aufruf zusätzliche Optionen für Dblatex an, die A2x entsprechend weiterreicht (Listing 5, Zeile 2). Die Tabelle “Dblatex-Optionen” fasst eine Auswahl gängiger Optionen zusammen [13].

Abbildung 4: Das mit A2x erzeugte PDF basiert auf Asciidoc, das die Software über einen Zwischenschritt ins endgültige Format konvertiert hat.

Abbildung 5 zeigt ein Beispiel aus der Praxis für ein Dokument mit Zielland USA. Dafür wurde das Encoding entsprechend angepasst und als Papierformat Letter ausgewählt.

Abbildung 5: Das mit FOP erzeugte PDF weist weniger Standardelemente auf und fällt aus diesem Grund sehr viel kompakter aus.

Der zweite Weg zum Umwandeln nach PDF führt über FOP. Dahinter verbirgt sich eine Java-Bibliothek unter der Ägide der Apache Software Foundation. Im Hintergrund konvertiert diese zunächst mittels Xsltproc Asciidoc nach Docbook (XSL-FO) und wandelt das Resultat danach mittels FOP nach PDF. Den dazugehörigen Schalter --fop geben Sie A2x beim Aufruf mit (Listing 5, Zeile 3).

Das Ergebnis sehen Sie in Abbildung 5. Es fällt deutlich kompakter aus als das mit Dblatex erzeugte. Zum Einsatz kommen hier Stilvorlagen in der Extensible Stylesheet Language (XSL). Über den Schalter --xsl-file=datei.xsl benennen Sie bei Bedarf eine eigene Vorlage.

Asciidoctor-pdf

Als Alternative zu den gezeigten Wegen bietet sich Asciidoctor-pdf an. Derzeit steht dieses Backend für Debian oder Ubuntu noch nicht als Paket bereit. Sie müssen es daher manuell als Gem aus dem Ruby-Universum beziehen und entsprechend installieren [14]. Danach erfolgt der Aufruf ohne weitere Parameter (Listing 6, erste Zeile).

$ asciidoctor-pdf document.adoc
$ asciidoctor-pdf \
   -a pdf-stylesdir=resources/theme \
   -a pdf-style=book \
   -a pdf-fontsdir=resources/font \
   document.adoc

Als Format für die Stilvorlagen kommt hier YAML zum Zug, eine vereinfachte Auszeichnungssprache, die zusammenhängende Blöcke nur über die Einrückung miteinander verbindet. Vom Konzept her lehnt es sich an Asciidoc an.

Für eine eigene Stilvorlage vergeben Sie einen Namen. In Zeile 4 von Listing 6 heißt diese book, sie gehört als Datei book-theme.yml ins Verzeichnis resources/theme/ (Zeile 3). Unter resources/fonts/ sucht Asciidoctor-pdf Schriften, die Sie einbinden möchten (Zeile 5). Der besseren Lesbarkeit halber erfolgt die Darstellung des Aufrufs ab Zeile 2 mittels explizitem Umbruch (\) – ideal zum Übertragen in ein Shell-Skript. Der hier verwendete Schalter -a steht als Kurzform für --attribute.

In der Vorlage legen Sie etwa das Layout der Seiten, die Abstände zwischen den Absätzen, die eingesetzten Fonts sowie die Farben fest. In Abbildung 6 sehen Sie einen Ausschnitt daraus, der das Layout mit der Farbe für den Hintergrund, der Ausrichtung (Hoch- oder Querformat), den Werten für die Rändern und dem Papierformat festlegt (hier: Letter).

Abbildung 6: Mit einem YAML-File (hier ein Ausschnitt) legen Sie die grundlegenden Parameter für das spätere Dokument fest.

Abbildung 7 zeigt, was als Gestaltung für die Ausgabe möglich ist. Die ersten vier Seiten umfassen ein Titelbild, Absätze mit Text, Aufzählungen sowie Tabellen mit unterschiedlichen Varianten für das Design.

Abbildung 7: Bei der Ausgabe als PDF setzt das Programm Asciidoctor-pdf die in einer YAML-Datei festgelegten Parameter in ein komplettes Layout um.

In der Stilvorlage dürfen Sie Variablen definieren. Das erfolgt im Beispiel für die Farben und Schriften in einer Tabelle (Abbildung 8). Einmal hinterlegt, erlauben solche Variablen das Anpassen an einer einzigen Stelle in der Konfiguration.

Abbildung 8: Setzen Sie Variablen in der Stilvorlage ein, haben Sie die Möglichkeit, einen ganzen Satz Parameter komfortabel an einer Stelle zu pflegen.

Fazit

Geht es um das Erstellen von HTML mit einem eigenen Stil, genügen dafür Kenntnisse in CSS. Den Ausgangspunkt bildet dann in der Regel eine bestehende Vorlage, die Sie nach Gusto anpassen. Beim Übersetzen nach HTML geben Sie die Vorlage als Parameter mit an.

Möchten Sie als Ergebnis ein PDF erzeugen, sieht die ganze Angelegenheit etwas komplexer aus: Hier hilft Vorwissen um die genutzten Subsysteme weiter, insbesondere Kenntnisse rund um LaTeX oder XSL. Das trifft auch auf das YAML-File von Asciidoctor-pdf zu.

Mit einer einzigen Vorlage vom Aussehen her identisches HTML und PDF zu erzeugen, bleibt weiterhin ein Wunschtraum – zu unterschiedlich sind Medien und Formate. Mehrere Versuche des Autors, derzeit noch bestehende Unzulänglichkeiten in der Auszeichnung bei Asciidoctor-pdf durch eine Kombination aus CSS und YAML zu umgehen, endeten darin, dass die Software stets eines der beiden Vorlagen ignorierte.

Zwar greifen explizite Workarounds im Asciidoc(tor)-Dokument – sie erfreuen allerdings nur Hacker, bringen jedoch Endanwender zur Weißglut. Für eine kurzzeitige Lösung mag das taugen, für den Alltag eher nicht.