Die Ausgabe von Asciidoc nach PDF anpassen

Asciidoc ist eine textbasierte Sprache (Markup Language). Diese vereinfacht es erheblich, (Text)Dokumente zu Erstellen, zu Pflegen und deren Änderungen in Revisionskontrollsystemen wie Git nachzuverfolgen. Aufgrund der Kompaktheit und Verständlichkeit der Sprache hat Asciidoc den Prozess zur gemeinsamen Erstellung und Pflege von Büchern, Dokumentation und Schulungsmaterial erheblich erleichtert.

Bei Asciidoc handelt es sich um Plaintext mit speziellen Markierungen. Erst durch den expliziten Aufruf eines Übersetzerprogramms wandeln Sie diesen Ursprungstext über mehrere Zwischenstufen in das gewünschte Zielformat um, bspw. zu Postscript, PDF, HTML, Epub und Handbuchseiten (Manpages). Im UNIX/Linux-Werkzeugkasten finden Sie dafür bspw. Asciidoc, a2x, Asciidoctor und Asciidoctor-pdf.

Der Weg von Asciidoc nach PDF funktioniert entweder über Dblatex oder über den Apache Formatting Objects Processor -- kurz FOP. Der erste Weg setzt auf die Werkzeugkette aus DocBook, xsltproc und Dblatex, der zweite nutzt statt Dblatex die auf Java basierende Software FOP. Beide Wege werden durch das Programm a2x gekapselt, d.h. mit einem einzigen Aufruf angestoßen. Für Dblatex sieht der Aufruf wie folgt aus:

a2x -f pdf document.adoc

Der Schalter -f pdf veranlasst a2x, das Backend Dblatex zu benutzen. Für die Verwendung von FOP nutzen Sie stattdessen diesen Aufruf:

a2x --fop document.adoc

Zur Demonstration nutzen wir dieses Asciidoc-Dokument, in den beiden vorherigen Aufrufen schlicht als document.adoc bezeichnet. Der darin genutzte Text stammt nicht vom Autor selbst, sondern wurde aus dem Wikipedia-Artikel zu Kapstadt entnommen und etwas bearbeitet.

:author: Frank Hofmann

= Visiting South Africa =

== Cape Town ==

Cape Town is a port city on South Africa’s southwest coast, on a peninsula beneath the imposing Table Mountain. Slowly rotating cable cars climb to the mountain’s flat top, from which there are sweeping views of the city, the busy harbor and boats heading for Robben Island, the notorious prison that once held Nelson Mandela, which is now a living museum.

image::capetown.jpg[width=200]

Die erzeugten Ergebnisse in der Ausgabe fallen durch die verwendeten Stilvorlagen recht unterschiedlich aus. Während der Weg über Dblatex sowohl ein Titelblatt, die Revisionshistorie des Dokuments sowie ein Inhaltsverzeichnis produziert, ist die Ausgabe via FOP deutlich kompakter.

Das erzeugte PDF via Dblatex

Das erzeugte PDF via FOP

Dblatex bietet eine Reihe von Schaltern, um die Elemente der Ausgabe zu verändern. Möglich sind zum Beispiel diese hier:

Bedeutung	Parameter
kein Inhaltsverzeichnis	-P doc.toc.show=0
nur Tabellenverzeichnis	-P doc.lot.show=table
nur Abbildungsverzeichnis	-P doc.lot.show=figure
Überschriftenebene	-P doc.section.depth=5
keine Versionshistorie	-P latex.output.revhistory=0
blau hinterlegte Links	-P latex.hyperparam=colorlinks,linkcolor=blue
als Encoding Latin1 nutzen	-P latex.encoding=latin1
Papiergröße Letter	-P paper.type=letterpaper
Wasserzeichen einfügen	-P draft.watermark=1
Schneidemarken einfügen	-P crop.marks=1

Im Aufruf sieht das dann wie folgt aus, um weder eine Revisionshistorie zu erhalten und lediglich eine Liste der Tabellen:

a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0 -P doc.lot.show=table" document.adoc

Am besten legen Sie das in einem Shellskript ab. Das erleichtert nicht nur das Experimentieren mit den Parametern, sondern auch die spätere Automatisierung im Übersetzungsprozess.

Automatisierung als Shellskript

Das obige Skript erwartet einen zusätzlichen Parameter im Aufruf. Dieser beinhaltet den Namen ihres Dokuments, welches Sie nach PDF übersetzen möchten. Benennen Sie ihr Skript convert2pdf.sh und übersetzen ihr Dokument namens document.adoc, sieht der Aufruf wie folgt aus:

./convert2pdf.sh document.adoc

Das fertige PDF-Dokument liegt dann im lokalen Verzeichnis vor.