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 |
| 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 |
./convert2pdf.sh document.adoc
Das fertige PDF-Dokument liegt dann im lokalen Verzeichnis vor.
