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.
