Technische Dokumentation mit Docbook und Zpub erstellen

Viele kleinere Unternehmen schreiben ihre Dokumentation mit einer Textverarbeitung wie Open Office Writer oder Word. Jeder, der im Team die Datei bearbeitet, kann neben dem Inhalt auch die Formatierung beliebig ändern. Ein einheitliches Layout, insbesondere über mehrere Dokumente hinweg, lässt sich so nur mit einer gehörigen Portion Selbstdisziplin erreichen.

Der Export der Daten in mehrere Ausgabeformate, etwa als PDF-Datei für den Druck, als Satz HTML-Dateien für das Internet und als CHM-Datei für die Onlinehilfe des Windows-Programms ist zwar möglich, aber etwa die Qualität des HTML-Exports einer Textverarbeitung ist dabei kaum zufriedenstellend.

Dazu kommt, dass ab einer gewissen Projektgröße mehrere Mitarbeiter und externe Hilfskräfte das Dokument ergänzen und überarbeiten sollen. Es mag naheliegend sein, die Dateien per E-Mail herumzuschicken. Doch wehe, zwei Autoren bearbeiten das Dokument gleichzeitig! Dann heißt es, sehr gut aufpassen, dass nicht eine der Änderungen verloren geht, und das Zusammenführen ist mühsame Handarbeit. Auch kann man später schwer nachvollziehen, auf wen welche Passage zurückgeht.

Der Retter: Docbook

Diese Probleme lassen sich mit freier Software lösen. Dabei kommt zum einen Docbook zum Einsatz. Dieses XML-Format, HTML nicht unähnlich, beschreibt den Inhalt eines Dokuments auf der semantischen Ebene. Es enthält keine Tags für Formatierungsangaben wie Fett- oder Kursivdruck, stattdessen gibt es eine sehr große Auswahl an Tags wie »<title>« oder »<productname>«. Diese Stilvorgaben verwandelt ein XSLT-Stylesheet erst später in konkrete Formatierungsanweisungen. Die nötigen Werkzeuge dafür sind in den meisten Linux-Distributionen bereits enthalten. So erstellen unter Debian etwa die Anweisungen

xsltproc /usr/share/xml/Docbook/stylesheet
/Docbook-xsl/xhtml/Docbook.xsl
document.xml > document.html

aus der Docbook-Datei »document.xml« eine einzige HTML-Datei und verwenden dabei das Standard-Stylesheet. PDF-Dateien generiert der Anwender über den Umweg einer Fo-Datei:

xsltproc /usr/share/xml/Docbook/stylesheet
/Docbook-xsl/fo/Docbook.xsl
document.xml > document.fo
fop document.fo document.pdf

Dabei ist »fop« der Formatting Objects Processor, der ebenfalls den gängigen Linux-Distributionen beiliegt. Anpassungen nimmt eine eigene XSLT-Datei vor, die das Standard-Stylesheet einbindet. Listing 1 ändert die Papiergröße auf A4 und aktiviert den Draft-Modus, der die Seite mit einem hellgrauen Text »DRAFT« hinterlegt. Das Buch [1] ist die kanonische Referenz zu Docbook, und [2] geht im Detail auf die Möglichkeiten der Anpassung der XSLT-Stylesheets ein. Beide Bücher sind online frei verfügbar.

01 <?xml version="1.0" encoding="UTF-8"?>
02 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
03         <xsl:import
04         href="/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl" />
05         <xsl:param name="paper.type" select="'A4'"/>
06         <xsl:param name="draft.mode">yes</xsl:param>
07 </xsl:stylesheet>

Ist das gewünschte Layout erst einmal in einen Satz von XSLT-Stylesheets umgesetzt, so erhält man daraus fortan hochwertige und einheitliche Dokumente. Die Autoren, die an den Docbook-Dateien arbeiten, können das Erscheinungsbild nicht mehr gefährden. Außerdem lässt sich später das Layout an zentraler Stelle ändern, ohne dass dabei viele Dokumente händisch zu aktualisieren wären.

Nicht jeder Mitarbeiter wird ein Docbook-Dokument im Quelltext bearbeiten wollen. Hier helfen XML-Editoren, die eine grafische Ansicht bieten, ohne dabei die Trennung von Inhalt und Layout aufzugeben (Abbildung 1). Verwendbar sind beispielsweise der proprietäre Java-Editor XMLmind [3] oder das freie Serna XML [4]. Beide laufen sowohl unter Linux als auch unter Windows.

Abbildung 1: Mit einem XML-Editor wie Serna fällt das Editieren der Docbook-XML-Files relativ leicht. Inhalt und Layout bleiben auch dabei getrennt.

Helfer Nummer zwei: Subversion

Arbeiten mehrere Redakteure an einer Docbook-Quelle, so drängt sich eine Versionsverwaltung (VCS, Version Control System) wie Subversion geradezu von allein auf. Sie erlaubt es jedem Mitarbeiter, sich alle Dokumente auf dem aktuellen Stand auf seinen Arbeitsplatz zu laden, dort lokal zu bearbeiten und sie dann als neue Version wieder im Repository abzuspeichern.

Dabei lässt sich jede Änderung kommentieren und mit Metadaten wie dem Namen des Autors versehen. Die gleichzeitigen Änderungen zweier Redakteure in verschiedenen Abschnitten der Datei führt Subversion später verlustlos wieder zusammen.

Ein recht nützliches Feature von Subversion ist, dass es im Dokument eine Markierung einfügen kann, die die aktuelle Revisionsnummer, das Datum der letzten Änderungen sowie den Namen des letzten Autors angibt. In der englischsprachigen Subversion-Dokumentation [5] heißt diese Funktion »keyword substitution«. Packt der Admin sie in das Docbook-Tag »releaseinfo«, sieht er jedem erzeugten Dokument auf einen Blick seinen Versionsstand an. Das ist besonders dann sehr nützlich, wenn die Seiten ausgedruckter Exemplare im Büro herumliegen.