© Bryan Fickett, 123RF

Zu guter Software gehört ausführliche Dokumentation. Wer keine Angst vor Quelltext hat, greift zum Format Docbook-XML, aus dem sich von der Manpage bis zum E-Book allerlei generieren lässt. Mit den offenen Publishing-Systemen Daps, Publican und Yelp bekommt ein Autor auch dicke Handbücher in den Griff.

Dokumentation für das durchschnittliche Softwaretool lässt sich bereits mit einfachsten Mitteln verfassen. Ein Readme für ein kleines Open-Source-Programm ist beispielsweise mit einem beliebigen Texteditor schnell geschrieben und liegt daher auch den meisten Quelltextpaketen bei. In den letzten Jahren greifen Entwickler für solche Dokumente gern auch zum Markdown-Format [1], das der Codehoster Github automatisch ansehnlich formatiert. Es beherrscht Aufzählungen, Listings und Weblinks.

Dicke Handbücher

Die Anwender leistungsfähiger Softwaresuites benötigen und erwarten hingegen deutlich umfangreichere Dokumente, sprich: richtige Handbücher. Das gilt insbesondere dann, wenn hinter der freien Software ein Unternehmen steht, das die Software auch in einer kostenpflichtigen Version mit Subskription und Support anbietet.

In dieser Liga spielt das Format Docbook [2], das in einer SGML- und XML-Ausprägung existiert. Damit trotzt es der Kritik, es sei zu wortreich und überladen, und behauptet sich auch gegenüber leichtgewichtigeren Konkurrenten wie etwa Restructured Text [3]. Von Inhalts- und Abbildungsverzeichnissen über Querverweise bis hin zum Index sieht es alles vor, was ein Entwickler für ein professionelles Handbuch benötigt.

Daneben hat es sich als eine Art Verkehrssprache der technischen Dokumentation etabliert. Freie Software kommt mit dieser Sprache ebenso zurecht wie proprietäre Anwendungen, beispielsweise Adobes Framemaker. Wer auf Docbook-XML setzt, muss sich keine Sorgen darum machen, ob er seine Dokumente auch in wenigen Jahren noch lesen und pflegen kann. Allerdings darf er keine Scheu vor der Arbeit mit XML-Quelltext haben, die er sich aber durch die Wahl eines geeigneten Editors erleichtert.

Bereits an Bord

Die Docbook-Schemata und eine Sammlung von XSL-Stylesheets zum Umwandeln in HTML und weitere Formate gehören zum Paketumfang praktisch jeder Linux-Distribution. Damit lässt sich Single-Source-Publishing verwirklichen, also das Erzeugen von Man-, Info-, HTML-, PDF- und Epub-Dokumenten aus demselben Quelltext. Ein Artikel im Linux-Magazin 02/14 [4] beschreibt, was sich mit Docbook alles anstellen lässt.

Ein praxistaugliches Publishing-System muss aber noch mehr bieten – insbesondere wenn mehrere Benutzer damit arbeiten sollen: Es sollte vorgeben, wo die zahlreichen XML-, Bild- und sonstigen Dateien eines Dokumentationsprojekts landen, den Build der Ausgabedateien automatisieren sowie sicherstellen, dass die Querverweise nicht ins Leere zeigen. Daneben sollte es in einem Rutsch das Gerüst für ein neues Dokumentationsprojekt anlegen, was insbesondere Einsteigern hilft.

Das Testfeld

Wer all das nicht mühsam selbst programmieren möchte, kann auf die Vorarbeit anderer zurückgreifen, die den Quelltext ihrer Software veröffentlicht haben. Das Doku-Team von Suse Linux hat für hauseigene Zwecke und für Open Suse die Docbook Authoring and Publishing Suite (kurz Daps, [5]) entwickelt. Ähnlichen Anforderungen begegnet Red Hat, das Projekte wie Fedora oder Ovirt betreibt, mit Publican [6]. Der dritte Kandidat sind jene Programme, die das Gnome-Projekt rund um den Hilfebrowser Yelp [7] hervorgebracht hat.

Daps

Mit Hilfe von Daps [5] entstehen unter anderem die Handbücher von Open Suse und Suse Linux Enterprise (Abbildung 1). Auf diesen Distributionen lässt sich die Suite daher einfach aus dem Paketrepository installieren. Für andere Linuxe listet die Installationsanleitung [8] die benötigten Pakete auf. Der eigentliche Code der Suite landet mit Hilfe von Git auf der Festplatte und lässt sich mit wenigen Kniffen direkt im geklonten Verzeichnis ausführen.

Abbildung 1: Die offizielle Suse-Dokumentation im Webhelp-Format entsteht mit Hilfe der hauseigenen Docbook Authoring and Publishing Suite (Daps).

Daps folgt dem üblichen Docbook-Rezept und transformiert das Docbook-XML mit Hilfe von »xsltproc« und der Docbook-Stylesheets in andere Formate wie (X)HTML, HTML Help, Manpage, Epub oder Webhelp. Letzteres ist Teil der jüngsten Docbook-Stylesheets, bietet eine aufklappbare Navigationsleiste und präsentiert etwa die SLES-Dokumentation übersichtlich im Web. Zudem gibt es die Umwandlung in XSL Formatting Objects (XSL-FO), die als Ausgangsmaterial für die PDF-Erzeugung mit dem Apache Formatting Objects Processor (Fop, [9]) dienen. Bash-Skripte und Makefiles halten die Komponenten zusammen.

Das zentrale Kommando lautet »daps« und kennt eine Unmenge Optionen und Parameter, von Checks über Transformationen bis hin zu Paketiermöglichkeiten. Ein neues Dokument legt der Befehl »daps-init« an, Abbildung 2 zeigt das Resultat. Die zentralen Einstellungen für das Publishing-Projekt enthält die »DC« -Datei, im XML-Verzeichnis liegt die Docbook-XML-Datei. Sie kann auch als Hauptdatei für modularisiertes XML dienen und beispielsweise die Kapitel aus separaten Dateien integrieren. Das »images« -Verzeichnis zeigt, welche Formatvielfalt Daps verarbeitet: Für Dia, Xfig und SVG generiert die Software zudem automatisch Ausgabeversionen beim Publizieren.

Abbildung 2: Das Kommando »daps-init« legt die Verzeichnisstruktur für ein neues Dokumentationsprojekt an.

Während der Schreibarbeit greift der Autor bei Bedarf auf passende Erweiterungen für die Editoren Emacs, Vim und Jedit zurück. Daneben unterstützt ihn Daps mit verschiedenen Optionen, die etwa das Docbook-XML validieren, Querverweise und Weblinks prüfen sowie benötigte oder verwaiste Dateien finden. Die Rechtschreibprüfung kommt dank Aspell auch mit den XML-Tags klar.

Fortgeschrittene Anforderungen der Dokumentation erfüllt die Suite ebenfalls. Unter den Schlagworten Conditional Text und Profiling erstellt sie mehrere Varianten eines Dokuments. Sie tauscht Produktnamen aus oder lässt Abschnitte über Features weg, die nur eine bestimmte Produktversion betreffen. Auch Anmerkungen und Draft-Wasserzeichen für Korrekturleser und Übersetzer lassen sich anbringen.

Neben den erwähnten Ausgabeformaten erzeugt Daps Tarballs, die wahlweise den XML-Quelltext oder die HTML-Hilfe enthalten. Auf Wunsch paketiert sie zudem die Dokumentation für RPMs oder die Hilfesysteme von Gnome und KDE.

Lost in Translation

Eine wichtige Aufgabe von Dokumentationsteams besteht darin, mit Übersetzern zusammenzuarbeiten. Dabei gilt es unter anderem, XML-Quelltext zu lokalisieren, Abbildungen auszutauschen oder Updates zu verwalten. Das Suse-Team verwendet zum Export der Dateien die Daps-Option »locdrop« und importiert die erledigte Übersetzung via »unpack-locdrop« . Daneben haben die Suse-Entwickler mit Docmanager [10] ein Open-Source-Werkzeug geschaffen, das mit Daps kooperiert und den Workflow der Dokumentationsprojekte mit Hilfe von Metadaten verwaltet.

Ein umfangreiches Benutzerhandbuch [11] und ein Quickstart-Guide – selbstverständlich mit Daps gemacht – erklären dem Anwender ausführlich, wie er die komplexe Suite bedient, und lassen kaum eine Frage offen.

Publican

Publican [6] findet sich nicht nur im Paketarchiv von Red Hat und Fedora, sondern auch bei Debian und Ubuntu. Auf Open Suse ist die Installation erst ab Version 12.1 möglich. Wie Daps können Entwickler das Publishing-System auch aus Git [12] auschecken, um die jüngste Version zu nutzen.

Red Hats System verwendet ebenfalls die Docbook-XSL-Stylesheets und Apache Fop, um vielfältige Ausgabeformate zu erzeugen. Als Integrationssprache dient Perl. In den Dateien »~/publican.cfg« und »Projektname/publican.cfg« finden wichtige Angaben wie Docbook-Version und Dokumentenklasse Platz.

Das Kommando »publican« kennt eine große Anzahl von Aktionen und besitzt eine sehr lange Manpage: »publican create« erzeugt ein neues Dokumentationsprojekt, »publican build« produziert Ausgaben von HTML über PDF bis hin zum Hilfeplugin für Eclipse, und »publican clean« löscht Temporärdateien.

Dabei kennt die Buildaktion auch das Format »test« . Das baut rein gar nichts, sondern prüft lediglich, ob sich eine bestimmte Sprachversion eines Dokuments auch fehlerfrei bauen lässt:

publican build --formats=test --langs=de-DE

Für die Internationalisierung und Lokalisierung haben sich die Publican-Entwickler einen praktikablen Workflow einfallen lassen und ihn gleich im Publican-Kommando eingebaut. Ein Dokumentenprojekt besitzt für jede Sprachversion ein eigenes Verzeichnis, das mit dem ISO-Sprachkürzel bezeichnet ist, beispielsweise »pt-BR« für brasilianisches Portugiesisch. So sorgt etwa das Kommando

publican update_po --langs=hi-IN,ru-RU

dafür, dass Publican aus dem Docbook-XML die zu übersetzenden Zeichenketten für Hindi und Russisch extrahiert und in passende Verzeichnisse packt.

Dabei kommt das PO-Format von GNU Gettext [13] zum Einsatz, für das es breiten Toolsupport gibt. Es eignet sich auch für Übersetzungsportale von Open-Source-Projekten, auf denen sich Ehrenamtliche die Arbeitspakete zum Übersetzen herauspicken. Publican unterstützt derzeit mehr als 40 Sprachen, wobei Standardinhalte wie die Formatierungskonventionen bereits lokalisiert sind.

Als Hilfen für den Arbeitsablauf eines Doku-Projekts bietet Publican Funktionen zum Aufspüren unbenutzter XML- oder Bilddateien, zum Anzeigen benutzter oder verbotener Docbook-Tags oder zum Paketieren an. Letzteres nicht nur als RPM, sondern auch zum Importieren in das CMS Drupal oder als Website mit Suchmaschinen-optimierter Sitemap.

Brands

Als Publikationssystem für RHEL, Fedora, Ovirt, Gimp & Co. verwendet Publican so genannte Brands, um die Dokumente an das Design der Marke anzupassen. Auch Debian hat eine eigene Publican-Marke im Paketarchiv. Daneben gibt es ein neutral aussehendes und gemeinfreies Paket namens »common« .

Ein Gestalter kann auch eigene Brands erzeugen. Das Kommando

publican create_brand --name=LM --lang=de-DE

erzeugt ein Stilverzeichnis für das deutschsprachige Linux-Magazin (Abbildung 3). Dessen Dateien enthalten das Wort »SETUP« an jenen Stellen, die der Anwender individualisieren muss. Sie lassen sich über das »grep« -Kommando leicht ausfindig machen (Abbildung 4). Daneben sind Standard-Bilddateien zu ersetzen, etwa das Logo, und das Stylesheet »overrides.css« zu bearbeiten. Publican kann Brands als RPM oder Tarball paketieren. Will er es nicht einpacken, gibt der Anwender über die Option »–brand_dir« an, welches Brand-Verzeichnis er verwenden möchte. Mit einem ausführlichen Handbuch [14] macht Red Hats Team das Open-Source-Tool rund.

Abbildung 3: Eine einfache Brand, wie die Gestaltungspakete bei Publican heißen, ist für das Linux-Magazin binnen Minuten gebastelt und auf das Dokument angewendet.

Abbildung 4: Mit Publican lässt sich die Grundlage für einen eigenen Look der Dokumente generieren. Stellen mit dem Wort »SETUP« muss der Entwickler individualisieren.

Yelp

Der Hilfebrowser der freien Desktopumgebung Gnome heißt Yelp [7]. Er zeigt unter anderem Docbook-Dokumente an, ohne dass der Entwickler diese zuvor transformieren muss (Abbildung 5). Ihn begleitet das Paket »yelp-tools« , das laut Yelp-Homepage kleine Programme zum Anlegen, Bearbeiten, Verwalten und Publizieren von Dokumenten enthält. Als unterstützte Eingabeformate nennt die Seite Docbook und Mallard [15]. Das zweite ähnelt Docbook, verwendet aber ein einfacheres Repertoire an XML-Elementen und sieht vor, für jeden Sinnabschnitt eine eigene Datei zu verwenden.

Abbildung 5: Gnomes Hilfebrowser Yelp zeigt auf Anhieb Docbook-Dokumente an, schwächelt aber bei der Dokumentation.

Wer Informationen zu einem Tool wie »yelp-build« nachschlagen möchte, bemerkt einerseits, dass die Dokumentation auf der Yelp-Homepage ziemlich spärlich ausfällt. Andererseits unterstützt das Tool zwar Docbook in den Versionen 4 und 5 – es scheint aber ein Bürger zweiter Klasse zu sein: Das attraktive Zielformat Epub bleibt Mallard vorbehalten, ebenso die Möglichkeit, beim Umwandeln einen Cache zu nutzen (Abbildung 6).

Abbildung 6: Die Yelp-Doku ist spärlich und zeigt eine starke Vorliebe für das Mallard-Format.

Auch zu »yelp-new« für neue Dokumente ist wenig nachzulesen, doch »yelp-check« kann sich immerhin sehen lassen: Es validiert Docbook-XML, prüft Querverweise und externe Links, stellt die Vollständigkeit der Bilddateien sicher und findet verwaiste Dateien.

Was den Yelp-Tools am meisten fehlt, ist kurioserweise ein ordentliches Handbuch, das dem Anwender ein Gesamtbild vermittelt: Wie er ein Dokumentationsprojekt anlegt und wie sich die einzelnen Tools in den Arbeitsablauf vom ersten Gerüst bis zu den Ausgabeformaten einfügen. Auch das Gnome-Wiki [16] hilft hier nicht weiter und nennt veraltete oder gar fehlende Seiten.

Zusammenfassung

Daps wie Publican sind ausgewachsene Systeme, mit denen Docbook-Profis – aber auch -Einsteiger – ihre Dokumentationsprojekte von Anfang bis Ende erledigen. Sie gehen sogar beide über einzelne Handbücher hinaus, denn sie unterstützen so genannte Sets, also Sammlungen von Büchern, bei denen sie sicherstellen, dass Querverweise von einem zum anderen funktionieren.

Daneben bietet jedes der beiden eigene Spezialitäten: Daps kennt die Webhelp-Ausgabe und beherrscht eine Menge Grafikformate, das Handbuch verrät zudem, wie der Entwickler bestehende Docbook-Projekte auf die Suite migriert. Publican hingegen macht das Anlegen eigener Brands einfach. Dabei ist die Suse-Fraktion bei Layout und Gestaltung auch nicht untätig, setzt aber auf die Anpassung der Docbook-XSL-Stylesheets. Teammitglied Thomas Schraitle hat ein komplettes Buch zum Thema als Open-Source-Projekt [17] entwickelt.

Ein weiterer Pluspunkt für das Red-Hat-Tool ist, dass Publican die Lokalisierung wie selbstverständlich integriert hat. Wer breite Sprachunterstützung umsetzen möchte, wird sich angesprochen fühlen. Daneben paketiert Publican RPMs für Fedora und RHEL und kommt mit Red Hats Buildsystem Brew klar.

Gnomes Yelp hat den Schwarzen Peter. Das liegt vor allem an der – ironischerweise – mangelhaften Doku des Dokumentationstools. Sie ist auch der Grund für die Lücken in der Gesamtübersicht dieser Bitparade in Tabelle 1. Die Docbook-Schwäche zählt aber nur, wenn man auf diesem Format beharrt, denn mit Mallard scheint sich die Gnome-Hilfe recht einfach schreiben zu lassen. Wissenswertes zu diesem Format liefert ein Artikel im Linux-User [18].

Ausblick

Ein Trend in der technischen Kommunikation nennt sich Topic-orientiertes Schreiben. Es verwaltet inhaltlich zusammenhängende Abschnitte als eigenständige Komponenten, setzt diese zu größeren Einheiten zusammen und recycelt sie. Wer etwa ein Topic zur Systemaktualisierung im Archiv hat, kann stets darauf verweisen, wenn erst einmal ein Update ansteht.

Mallard zeigt eine Tendenz zur Topic-Orientierung, doch das Schlagwort unter Dokumentationsautoren lautet Darwin Information Typing Architecture, kurz Dita [19]. Wie bei Docbook wird die Spezifikation der XML-Architektur von einem Komitee der Standardisierungsorganisation Oasis gepflegt. Mit dem Dita Open Toolkit [20] steht bereits eine Sammlung nützlicher Werkzeuge unter Apache-Lizenz bereit. Auch die Yelp-Entwickler experimentieren mit Dita.