© Lim Jerry, Fotolia.com

Die letzte Zeile Code ist geschrieben, das Makefile übersetzt das eigene Softwarepaket. Doch halt! Die Dokumentation fehlt! Nur wenige Entwickler mögen das einige Jahrzehnte alte Troff-Format, in dem Manpages formuliert sind. Docbook beendet die Schreibblockade.

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.

Erklärungen abgeben

Den Abschnitt »NAME« mit einer Kurzbeschreibung der Aufgabe des Programms definiert der XML-Container »refnamediv« ab Zeile 9: Hier steht erneut der Name des beschriebenen Tools in »refname«. Eine einzeilige Zusammenfassung in »refpurpose« erklärt seinen Zweck. Als Nächstes steht die Synopse im Element »synopsisdiv« an, eine Zusammenfassung, die die Syntax knapp beschreibt. In Listing 2 steht dazu das entsprechende XML-Markup.

01   <refsynopsisdiv>
02     <cmdsynopsis>
03       <command>jpeg2pdf</command>
04       <arg choice="opt">
05         <option>ahrvV</option>
06       </arg>
07       <arg choice="req">
08         <replaceable>directory</replaceable>
09       </arg>
10       <arg choice="req">
11         <replaceable>pdf</replaceable>
12       </arg>
13     </cmdsynopsis>
14   </refsynopsisdiv>

Jedes Argument des Kommandos listet ein »arg«-Element auf. Besitzt es ein »choice«-Attribut mit dem Wert »opt«, so ist das Element optional. Ist es hingegen notwendig, notiert der Entwickler es mit dem Wert »req«. Egal ob optional oder nicht, die einzelnen Argumente bestehen aus Teilen, die der Anwender später exakt eintippen muss, etwa die Option »-v« für mehr Debugging-Output. Solche Angaben kleidet der Entwickler in ein »option«-Element. Im Beispiel gibt es gleich fünf Schalter: »a«, »h«, »r«, »v« und »V«. Sie dürfen alle hintereinander in einem Element stehen (Zeile 5).

Soll der Anwender hingegen später einen Eintrag durch eigene Werte ersetzen – etwa durch einen Dateinamen -, notiert dies der Entwickler in einem »replaceable«-Container. Im Beispiel hat der Anwender also die Wahl aus fünf Flags, muss aber in jedem Fall ein Verzeichnis und einen Pfad zur späteren PDF-Datei angeben. Die beiden Container »refnamediv« und »refsynopsisdiv« regeln die formellen Anteile einer Manpage. Weitere »refsection«-Elemente erzeugen die weiteren Abschnitte in einer etwas freieren Form. Listing 3 bereitet eine »DESCRIPTION« vor.

01   <refsection>
02     <title>Description</title>
03     <para><command>jpeg2pdf</command> is a free program that converts
04      a directory of JPEG files to a PDF file. Each page of the PDF file
05      contains one of the JPEG images. So, you can make one document of
06      a list of cartoons, photos or scanned images
07     <command>jpeg2pdf</command> has the following features:</para>
08     </para>
09     <itemizedlist>
10       <listitem><para>
11        <command>jpeg2pdf</command> is <emphasis>fast</emphasis>.</para>
12       </listitem>
13       <listitem>
14         <para><command>jpeg2pdf</command> generates <emphasis>compact
15         pdf files</emphasis>. It doesn't do any processing/rescaling of
16         the images, nor does it generate thumbnails of the pages in the
17         pdf file.</para>
18       </listitem>
19       <listitem>
20         <para><command>jpeg2pdf</command> is <emphasis>free</emphasis>.
21         You can download it and use it for free.</para>
22       </listitem>
23     </itemizedlist>
24   </refsection>

Mit Stil gewandelt

Wer sich schon ein wenig mit Docbook auskennt, merkt schnell, dass ein »refsection«-Container einem Kapitel in einer Docbook-Datei entspricht: Er hat einen Titel und eine Reihe von Inhaltselementen. Ein Textabsatz steht in einem »para«-Container, ähnlich zu »p« in reinem HTML. Er darf sowohl eine »itemizedlist« wie auch eine »orderedlist« für Aufzählungen enthalten. Docbook zeichnet seine Elemente semantisch aus, daher sollten Manpage-Autoren darauf achten, Toolnamen immer in »command«-Tags, Ausgaben in »computeroutput« und Dateinamen in »filename« einzuschließen. Eine komplette Liste von erlaubten Tags enthält die Dokumentation [3].

Haben Entwickler die »DESCRIPTION« fertiggestellt, gehen sie bei allen weiteren Abschnitten nach dem gleichen Muster vor. Anwender erwarten insbesondere im Kapitel »OPTIONS« eine detaillierte Erläuterung jedes erlaubten Parameters. Kontaktdaten stehen in »AUTHOR«, eventuelle Rückgabewerte sollte »EXIT STATUS« erläutern und hilfreiche Beispiele finden ihren Platz in »EXAMPLES«. Wenn ein dokumentiertes Programm auf festgelegte Dateien zugreift, sollten die in »FILES« aufgeführt sein.

Oft steht aber zum Zeitpunkt, an dem der Entwickler die Handbuchseite schreibt, noch gar nicht genau fest, wo der Befehl nach den Dateien sucht, etwa in »/usr/local/share« statt in »/usr/share«. In diesem Fall bietet es sich an, einen Platzhalter in die XML-Datei zu schreiben und ihn später bei der Installation mittels »sed«-Skript zu ersetzen. Auch die Troff-Ergebnisse sind reine Textdateien, die sich gut mit den Standardwerkzeugen bearbeiten lassen. Entwickler schauen sich das am besten von den Installationsroutinen bestehender Softwarepakete ab. Hat der Anwender die XML-Datei mit einem normalen oder speziellen XML-Editor fertiggestellt, wandelt ein XSLT-Prozessor sie mit Hilfe eines Stylesheet ins Troff-Format um. Der Aufruf

xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl jpeg2pdf.xml 

sorgt dafür, dass der XSLT-Prozessor mit Hilfe des Stylesheet aus dem Paket »docbook-xsl« die Datei »jpeg2pdf.1« erzeugt. Wer das Paket »mandb« installiert hat, in dem das »man«-Kommando selbst enthalten ist, darf mit der Option »-l« gleich ausprobieren, ob die neue Handbuchseite so aussieht wie gewünscht:

man -l jpeg2pdf.1

Das Suffix ».1« ist dabei ein Zeichen für die den Handbuchabschnitt “Allgemeine Kommandos”. Wer in einem größeren Projekt Handbuchseiten für mehrere Aufrufe verwalten muss, benötigt dazu nur eine einzige XML-Datei: Er schreibt einfach mehrere »refentry«-Elemente in sie hinein. Die Struktur eines solchen Projekts skizziert Listing 4.

01 <?xml version="1.0"?>
02 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
03 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
04 <reference><title>Reference Pages</title>
05   <refentry>
06     <!-- ... -->
07   </refentry>
08 
09   <refentry>
10     <!-- ... -->
11   </refentry>
12 </reference>

Wendet der Entwickler nun das Stylesheet auf die XML-Datei an, entsteht für jeden Eintrag eine eigene Datei. Wichtig ist dabei nur, dass die Kombination aus »reftitle« und »resection« eindeutig ist. Das Prinzip ist sogar noch flexibler: Weil das Stylesheet für Manpages nur die beschriebenen Container betrachtet, lassen sich auch andere Dokumentationsteile in einer einzigen Datei pflegen. Der XSLT-Prozessor wertet aber nur die in Frage kommenden Abschnitte aus. Eine umfassende PDF-Dokumentation lässt sich dennoch aus der gleichen Datei erzeugen.

Ausgaben frisieren

Wer mit dem Ergebnis zufrieden ist, der ist an dieser Stelle fertig. Tüftler wollen aber vielleicht die Art, wie die Werkzeuge die Manpages gestalten, noch feiner justieren. Dazu bietet das Stylesheet eine Reihe von Parametern an (siehe Tabelle 1): Zeilenbreite, Silbentrennung, Einrückungen, Schriftarten, Listen, Kopf- und Fußzeilen sowie viele weitere Layout-Einstellungen sind konfigurierbar [4]. Perfektionisten und Kontrollfreaks sollten also einen Blick auf die Voreinstellungen werfen. Will ein Anwender Parameter auf Dauer ändern, schreibt er sich ein Driver-Stylesheet wie in Listing 5. Dort trägt er seine persönlichen Parameter ein und ruft in Zeile 6 das eigentliche Stylesheet auf. Nennt er es »my-docbook-man.xsl«, so erzeugt

xsltproc docbook-man.xsl jpeg2pdf.xml

künftig individualisierten Troff-Quelltext und überschreibt die Vorgaben. So gelingen etwa die Pfade für deutsche Seiten.

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>

Ordnung im Regal

Manpages sind eine unverzichtbare Hilfe für Linux-Admins und -Anwender. Ihre standardisierte Form ermöglicht schnelles Nachschlagen von Optionen und Aufrufparametern. Docbook erlaubt es Entwicklern mit überschaubarem Aufwand, solche Handbuchseiten deutlich komfortabler als in reinem Troff-Format zu verwalten. Das geht so weit, dass komplette Dokumentationen in einer XML-Datei stecken und ein Aufruf eines Skripts nur die Manpages erzeugt.

Weil sich die Ausgabe noch in einigen Bereichen steuern lässt, eignet sich das Verfahren besonders für automatische Build- und Installationsroutinen. Einzig die Installation in das Man-Verzeichnis, das in der Umgebungsvariablen »MANPATH« oder als Voreinstellung zumeist in »/usr/share/man« steht, muss der Entwickler noch von Hand oder per »Makefile« erledigen. Setzt er noch die Parameter »man.output.in.separate.dir« und »man.output.subdirs.enabled« auf »1« sowie »man.output.base.dir« auf »man/«, so erzeugt das Docbook-Stylesheet gleich die richtige Verzeichnisstruktur, die

cp -r man /usr/share/man

an die richtige Stelle kopiert. Wer alles aus Docbook herausholen will, darf im Definitive Guide [5] beziehungsweise in der Manpages Parameter Reference [6] versinken. (mg)