Manpages mit Docbook schreiben

Linux-Programme, die etwas auf sich halten, bringen eine Manpage mit, das Kommando »man« zeigt sie an. Alle Einträge zusammen bilden die in acht Abschnitten organisierte Unix-Referenz. Sie verwendet dazu als Quellformat die Troff-Formatierungssprache, erst der Man-Aufruf erzeugt eine formatierte Ausgabe. Troff und seine Vorgänger stammen aus den 1960er Jahren und gelten trotz ihrer Textform als mühsam zu schreiben und zu pflegen (siehe Abbildung 1). Sie verlangt, fast jede Steueranweisung an den Anfang einer neuen Zeile zu schreiben, selbst wenn sie mitten in einem Satz vorkommt - per Hand ist das ziemlich aufwändig.

Abbildung 1: Manpages benutzen auch heute noch das aus den 1960er Jahren stammende Troff-Format. Auf diese Weise Dokumentationen zu schreiben, ist aber sehr mühsam.

Da gelingt es leichter, die Handbuchseiten in XML zu verfassen. Ein Docbook-Stylesheet [1] und ein XSLT-Prozessor konvertieren sie anschließend. Selbst wenn Experten die Lesbarkeit von XML-Quelltext für Menschen anzweifeln, ist das immer noch einfacher, als reinen Troff-Quelltext zu schreiben. So kommen Entwickler dem Anwenderwunsch nach, für jedes Kommando eine Manpage auf dem eigenen System zu finden.

Nach der Posix-Definition setzen sich die Handbuchseiten aus standardisierten Abschnitten, den Sections, zusammen [2]. Jede Seite sollte mindestens die Abschnitte »NAME«, »SYNOPSIS«, »DESCRIPTION« und »SEE ALSO« enthalten. Der erste von ihnen enthält den Namen des Kommandos oder des Aufrufs und seinen Zweck. Die Synopse ist eine etwas ausführlichere Zusammenfassung der Syntax und der Optionen des Befehls. Der Abschnitt »DESCRIPTON« schließlich erläutert die Bedeutung der einzelnen Parameter und Optionen.

Autoren von Manpages dürfen eine Reihe weiterer Abschnitte hinzufügen: »AUTHOR«, »COPYRIGHT«, »ENVIRONMENT«, »EXIT STATUS«, »FILES«, »KNOWN BUGS«, »OPTIONS«, »REPORTING BUGS« oder weitere Abschnitte, die der Standard nicht spezifiziert. Dabei verstehen sich die Manpages als Referenzhandbuch, um die exakte Syntax einer Option nachzuschlagen, und weniger als Tutorium, das ein Thema oder alternative Umsetzungen diskutiert.

Eines für alle

Docbook ist ein XML-Format für technische Dokumentationen. Es erlaubt Autoren, Text unabhängig vom späteren Ausgabeformat zu schreiben und zu pflegen. Die Ergebnisse lassen sich später in einer Vielzahl von Formaten nutzen, darunter als PDF, HTML oder eben als Manpage. Viele Projekte nutzen Docbook für ihre Dokumentation, darunter der Linux-Kernel, Gnome, KDE, FreeBSD und das Linux Documentation Project.

Eine Docbook-Datei in eine vom Anwender lesbare Form zu bringen, ist die Aufgabe von XSL-Stylesheets. Sie erzeugen die jeweiligen Zielformate und lassen sich über eine Reihe von Parametern konfigurieren. Wer nur Manpages schreiben möchte, benötigt das Manpage-Stylesheet, das aus XML das Troff-Format erzeugt. Er muss danach nur noch dafür sorgen, dass die Installationsroutine seiner Software die Datei in das dafür vorgesehene Verzeichnis installiert. Alles andere bringen die Docbook-DTD mit der Sprachdefinition, die zugehörigen Stylesheets und der XSLT-Prozessor mit. Bei Debian und Derivaten heißen die Pakete »docbook-xml«, »docbook-xsl« und »xsltproc«.

Ins Verzeichnis eintragen

Um zu demonstrieren, wie Entwickler ihre eigene Manpage schreiben, soll ein fiktives Konvertierungswerkzeug namens »jpeg2pdf« herhalten. Listing 1 zeigt, wie der neue Eintrag in XML aussieht. Das Element »refmeta« ab Zeile 5 enthält die Informationen, die das Man-System benötigt, um die Seite später einzusortieren: In »manvolume« steht der Abschnitt, im Container »refentrytitle« legt der Entwickler den Namen des Werkzeugs ab.

01 <?xml version="1.0"?>
02 <xsl:stylesheet version="1.0"
03   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
04   xmlns:fo="http://www.w3.org/1999/XSL/Format">
05 
06   <xsl:import href ="/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl"/>
07   <xsl:param name ="man.links.are.numbered">
08     1</xsl:param>
09   <!-- ... -->
10 </xsl:stylesheet>

Der vorliegende Konverter ist für Anwender gedacht und steht daher im Abschnitt 1. Bibliotheksaufrufe landen in Sektion 3, administrative Kommandos in Sektion 8. Mit diesen Angaben bereitet der Prozessor die Datei für ihren späteren Platz in »/usr/share/man/man1/jpeg2pdf.1« vor. Im zugehörigen Verzeichnis liegen alle Manpages der Sektion 1. Um das Kopieren an die richtige Stelle muss sich der Entwickler selbst kümmern, etwa durch einen geeigneten Eintrag im »Makefile« seines Projekts.

Wer Handbuchseiten für mehrere Sprachen anbieten will, fügt dem obersten Element beispielsweise noch das Attribut »lang="de"« hinzu. Die weitere Verwaltung von Pfaden übernimmt Docbook, sie lässt sich mit später erläuterten Parametern steuern.