Text mit Extras: Asciidoctor auf Tomcat nutzen

Inhaltsverzeichnis

Menschen legen Notizen in unterschiedlicher Form an. Der Autor dieses Artikels nutzt für seine kurzen Aufzeichnungen häufig einen einfachen Texteditor wie Codemirror. Um das Ergebnis später in die passende Form zu bringen, eignet sich Asciidoctor gut. Ein Artikel vom Januar auf heise Developer zeigt, wie Entwickler es für Documentation as Code nutzen können.

Neben der reinen Dokumentation lässt sich mit ein paar Handgriffen die Transformation nach HTML in eine Anwendung einbauen, die das Ergebnis ausliefert. Apache Tomcat ist in diesem Zusammenhang das Mittel der Wahl. Der Server lässt sich in wenigen Schritten erweitern, um Text mit Auszeichnungen in HTML zu wandeln.

Von den Auszeichnung zu HTML

Asciidoctor interpretiert spezielle Auszeichnungen in Texten. Sie strukturieren und formatieren den Text und sind üblicherweise in Dateien mit der Endung .adoc gepeichert, die Dateien im Asciidoctor-Format kennzeichnet.

Ziel ist, Textdateien mit Auszeichnungen für Asciidoctor nach HTML zu überführen, um sie anschließend passend formatiert auszugeben. Die Transformation von Text zu HTML und die Ausgabe der HTML-Dateien soll Tomcat erledigen. Zusätzlich soll die Fähigkeit von Asciidoctor zum Einsatz kommen, aus demselben Quellformat unterschiedliche Zielformate zu produzieren, indem Tomcat alternativ PDF ausgeben soll.

Konkret soll die Anwendung folgende Anforderungen erfüllen:

• die .adoc-Datei als HTML oder PDF ausgeben,
• die Transformation nach Bedarf automatisiert erledigen und
• die HTML- und PDF-Fassungen einer .adoc-Datei speichern und nur neu erstellen, wenn sich etwas geändert hat.

Die Puzzleteile von Asciidoctor

AsciidoctorJ ist die offizielle Implementierung von Asciidoctor für Java und gut für den Einsatz mit Tomcat geeignet. Sie ist von Bintray und Sonatype frei erhältlich, und beide Quellen liefern eine Fassung als gepackte Datei, die die Bestandteile des Tools als Sammlung von Java-Klassenbibliotheken enthält.

Entwickler können zum Herunterladen von AsciidoctorJ die Downloadübersicht besuchen und einen der dortigen Verweise namens "distribution (zip)" herunterladen. Nach dem Download und Entpacken findet sich ein neuer Ordner auf dem lokalen Rechner, der im Unterordner lib als Klassenbibliotheken von Asciidoctor folgende Dateien enthält (Stand Juni 2020):

• asciidoctorj-2.2.0.jar
• asciidoctorj-api-2.2.0.jar
• asciidoctorj-diagram-2.0.0.jar
• asciidoctorj-epub3-1.5.0-alpha.9.jar
• asciidoctorj-pdf-1.5.0-beta.8.jar
• jcommander-1.72.jar
• jruby-complete-9.2.9.0.jar

Das Standard-Stylesheet zur Darstellung eines von Asciidoctor erzeugten HTML-Dokuments liegt im Java-Archiv namens asciidoctorj-2.2.0.jar. Im darin befindlichen Ordner /gems/asciidoctor-2.0.10/data/stylesheets findet sich die Datei asciidoctor-default.css. Entwickler können das Stylesheet kopieren und nach Bedarf mit von Asciidoctor erzeugten HTML-Dateien verwenden.

Für die Installation genügt es, die Klassenbibliotheken in den Ordner CATALINA_BASE/lib von Tomcat zu kopieren. Nach einem Neustart bindet der Server sie von dort automatisch ein, und alle Funktionen von Asciidoctor sind einsatzbereit.