von Patrick Gundlach | 27. March 2018

So wird das Handbuch erzeugt

Lange habe ich nach einem halbwegs vernünftigen Workflow gesucht, um mein Handbuch zu erstellen. Inzwischen ist es ja online verfügbar, daher ist es jetzt eine gute Gelegenheit, die benutzten Tools aufzuzeigen. Doch zuvor gibt es ein paar Hintergründe, warum ich diesen Weg gewählt habe.

Notwendige Eigenschaften des Workflows

OpenSource-Tools: alle Komponenten und Konverter müssen frei verfügbar sein. Das ist mir sehr wichtig, nicht nur, weil ich selber ein großer Verfechter des OpenSource-Gedankens bin. Vielmehr ist mir wichtig, dass ich die Dokumentation auf einem Unix-Rechner (Mac, Linux) automatisch erzeugen lassen kann, ohne Gedanken über die Gültigkeit von Softwarelizensierungen machen zu müssen.
Verschiedene Ausgabeformate. Zwar ist HTML das Hauptziel, trotzdem möchte ich in der Lage sein, ein hochwertiges PDF und ggf. auch ein ebook-Format (z.B. epub) zu erzeugen. Für HTML gibt es ja etliche Werkzeuge, für hochwertiges PDF aber fast nur LaTeX. (Und falls jemand »dogfooding« in den Raum wirft: der speedata Publisher ist für Produktkataloge und Datenblätter etc. aus XML-Quellen spezialisiert, für Handbücher ist das gute alte LaTeX immer noch das Mittel der Wahl.)
Single-Source Publishing. Also: nur eine Quelle für die Dokumentation haben, nicht mehrere. Was passiert, wenn man mehrere verschiedene Quellen pflegen muss, brauche ich nicht auszuführen.
Die HTML-Ausgabe soll aus mehreren Seiten bestehen. Der Text des Handbuches ist so umfangreich, dass die Benutzerführung arg darunter leiden würde, wäre die HTML-Datei eine lange Seite.
Bequemes editieren von Quelldateien.

Auf den letzten Punkt möchte ich etwas ausführlicher eingehen.

Bequemes editieren von Quelldateien

Das ist natürlich sehr subjektiv, man kann hervorragend darüber streiten, was »bequem« ist. Folgende Eigenschaften hätte ich gerne, damit ich Texte schnell und ohne große Schmerzen bearbeiten kann.

Plain Text Eingabeformat, am besten eine leichte Markup-Sprache wie Markdown. Ich möchte nicht zwischen LaTeX oder DocBook-Tags navigieren.
Direkte oder zeitnahe Vorschau. Ich möchte die Änderungen, die ich mache, unmittelbar oder ohne merkliche Verzögerung sehen.
Leichtes Verlinken zu anderen Textteilen.
Unterstützung von Git (Änderungen nachverfolgbar). Mit dem ersten Punkt ist das gegeben.

Ausgangspunkt: das RELAX NG Schema

Vorhanden ist die Datei commands.xml, aus der ich das RELAX NG Schema erstelle. Genau genommen sind es zwei, je eines mit deutscher und englischer Beschreibung der Befehle. Den Konverter dazu habe ich in Go geschrieben, weil mir XSLT mit de Saxon doch manchmal viel zu langsam ist…

Die Datei commands.xml möchte ich weiterhin als Grundlage für den Referenzteil benutzen, da hier formal beschrieben ist, welche Parameter (Attribute) jeder Befehl haben kann, eine Kurzbeschreibung dazu, ein Beispiel und weiterführende Informationen.

<command en="AttachFile" since="3.1.1">
    <description xml:lang="en">
      <para>Attach a ZUGFeRD file.</para>
    </description>
    <description xml:lang="de">
      <para>Binde eine ZUGFeRD Datei ein.</para>
    </description>
    <childelements/>
    <attribute en="filename" optional="no" type="text">
      <description xml:lang="en">
        <para>The name of the local file to be attached to the PDF.</para>
      </description>
      <description xml:lang="de">
        <para>Der Name der Datei, die in die PDF-Datei eingebettet werden soll.</para>
      </description>
    </attribute>
    ...
    <example xml:lang="en">
      <listing><![CDATA[<AttachFile filename="invoice.xml" description="A ZUGFeRD invoice." type="ZUGFeRD invoice"/>]]></listing>
    </example>
    <example xml:lang="de">
      <listing><![CDATA[<AttachFile filename="invoice.xml" description="ZUGFeRD Rechnung" type="ZUGFeRD invoice"/>]]></listing>
    </example>
    <seealso/>
</command>

Quellformat für das Handbuch

Es liegt nahe, Markdown als Quellformat für die übrigen Teile des Handbuchs zu benutzen. Mit dem statischen Seitengenerator HUGO zusammen sind die Punkte oben einigermaßen erfüllt, doch mir fehlen bei Markdown viele semantische Auszeichnungen wie Indexeinträge, Abbildungsunterschriften, Fußnoten, Tabellen, Definitionslisten, … Außerdem fehlt mir bei Markdown die formale Strenge, die ein XML-basiertes Format wie DocBook hat. Aber DocBook-Dateien zu bearbeiten macht nun wirklich nur begrenzt Spaß und erfüllt meine Voraussetzungen (teilweise) nicht.

DocBook als Zwischenformat

Nach langem Suchen und Testen bin ich auf das Format AsciiDoctor gestoßen, das im Prinzip zwei Ausgabeformate hat: HTML und DocBook. Das HTML Format hat leider den Nachteil, dass es immer eine einzige Seite erzeugt. Somit bleibt DocBook übrig. Da man aus XML mit XSLT leicht andere Formate erzeugen kann, insbesondere wenn diese wiederum textbasiert sind (wie HTML und LaTeX), ist das für mich die Lösung der Problem oben.

Live-Preview während der Eingabe

Ich habe oben erwähnt, dass AsciiDoctor auch HTML erzeugt. Das nutze ich, wenn ich das Handbuch bearbeite. Von HUGO habe ich mir eine Funktionalität geklaut, die ich sehr praktisch finde. Speichert man im HUGO-Baum eine Quelldatei, so aktualisiert sich der Browser selbständig. Mit dieser quasi-Live-Vorschau sieht man schnell, ob eine Formatierung auch richtig angewendet wird. Das habe ich für AsciiDoctor angepasst und so kann ich immer nahezu sofort im Browser sehen, ob alles richtig ist.