Eine befreundete Firma hat mittlerweile gemerkt, dass sie auch dem hier beschriebenen Problem aufgesessen ist. Schließlich kann ja jedes Kind Word bedienen, oder? So gern ich in diesen Momenten am liebsten Sätze wie “Ich hab’s dir ja gesagt.” von mir geben würde, biete ich in solchen Situationen auch gern meine Hilfe an. Aus diesem Grund wird nun testweise eins der Dokumente, die regelmäßig aktualisiert und versioniert Dritten zur Verfügung gestellt werden, auf AsciiDoc umgestellt. Im selben Zug soll auch gleichzeitig noch git zur Änderungsverfolgung und Versionierung eingeführt werden, aber das ist eine andere Herausforderung, über die ich vielleicht ein andermal schreiben werde.

Ich muss zugeben, dass ich mich über diese Aufgabe auch gefreut habe. So hatte ich nun endlich einen Grund, mich genauer mit AsciiDoc zu beschäftigen und konnte die leider eh schon vernachlässigten Pet-Projekte noch weiter nach hinten schieben. Ich muss sagen, dass sich mein erster positiver Eindruck über AsciiDoc nur weiter verstärkt hat. Da es der Firma darauf ankommt, am Ende ein PDF im Corporate Design zu haben, war ich froh auf Asciidoctor PDF gestoßen zu sein, welches direkt aus AsciiDoc PDFs generiert. Der “Umweg” mit DocBook als Zwischenformat bei der Generierung des PDFs gefiel mir nie, vor allem weil ich weiß, wie aufwendig teilweise solche Designanpassungen bei DocBook sein können.

Asciidoctor PDF ist komplett in Ruby geschrieben und ist auch auf Windows-Systemen problemlos installierbar. Alle möglichen Designanpassungen von Asciidoctor PDF sind im Theming-Guide dokumentiert und werden dann in einer YAML-Datei konfiguriert.

!!! warning “Achtung” Damit es keine Probleme mit Nicht-ASCII-Zeichen (bspw. Umlaute) gibt, ist es wichtig, dass die Kommandozeile, mit der Asciidoctor PDF aufgerufen wird, mit UTF-8 encodiert ist. Das sollte unter Linux direkt der Fall sein, aber unter Windows muss dafür der Befehl chcp 65001 vorher ausgeführt werden.

Ein Punkt, der mir auch einige Zeit Kopfzerbrechen bereitet hat, ist die fehlende Konfigurierbarkeit des Deckblatts. Man stolpert an vielen Stellen über die unterschiedlichsten Anforderungen an ein Deckblatt, die sich so erstmal nicht erfüllen lassen. Aber für jedes Problem gibt es eine Lösung und auch in diesem Fall habe ich eine Lösung gefunden, die mir sehr gut gefällt. Es gibt nämlich in AsciiDoc die Möglichkeit, über die Option :front-cover-image: ein Bild einzubinden, welches direkt hinter dem Deckblatt gerendert wird. Kombiniert man dies mit der Option :notitle:, die verhindert, dass das eigentliche Deckblatt gerendert wird, erhält man als Resultat ein maßgeschneidertes Deckblatt. Das “Front-Cover-Image” ist einfach ein PDF, dass ich mit LibreOffice Writer erstellt habe.

Aber in einem Punkt muss ich mir auch widersprechen. Ich habe damals AsciiDocFx als Editor angepriesen, bin jedoch mittlerweile zu der Entscheidung gekommen, dass Visual Studio Code gepaart mit den Plugins von asciidoctor der bessere Editor ist.