Dokumentation schreibt sich nicht von selbst. Das etablierte Werkzeug Help2man erspart Ihnen jedoch eine Menge der oft ungeliebten Arbeit.

Seit langer Zeit setzt das GNU-Projekt bei den Handbüchern von Befehlszeilenprogrammen auf das Texinfo-Format. Das konkurrierende Groff-Textformat kommt insbesondere bei Debian bevorzugt zum Einsatz und ist – nicht zuletzt wegen Debians zahlreicher Ableger – das wohl am weitesten verbreitete Format für Dokumentation von Programmen für die Befehlszeile.

Beide Varianten erschließen sich nicht gerade eben schnell, bedingt durch zahlreiche Optionen und eine über Jahrzehnte gewachsene, bisweilen regelrecht verklumpte Syntax. Ein von einem Debian-Entwickler betreutes Tool namens Help2man [1] hilft aber dabei, Programme dennoch mit einer vernünftig formatierten Hilfeseite auszuliefern.

Zusätzlicher Aufwand entfällt dabei erfreulicherweise weitestgehend. Sofern der Aufruf des Programms, das Sie dokumentieren möchten, mit den Parametern --help und --version beziehungsweise deren Kurzformen -h und -v brauchbare Ergebnisse liefert, steht im Prinzip schon alles Nötige bereit.

Kombinieren Sie nun Help2man mit dem entsprechenden Programmaufruf (Listing 1, erste Zeile), baut es aus den Ausgaben mit den zwei genannten Argumenten die Dokumentation und schreibt sie in die Standardausgabe (Abbildung 1). Mit der Option -o leiten Sie die Ausgabe in eine Datei um (Listing 1, zweite Zeile). Kommen statt der üblichen --help und --version andere Schalter für Hilfe und Versionsnummer zum Einsatz, übergeben Sie diese einfach mit -h und -v an Help2man (Listing 1, letzte Zeile).

$ help2man /usr/bin/help2man
$ help2man /usr/bin/help2man -o ~/help2man.1
$ help2man /usr/bin/foo -h --help-all -v --release -o ~/foo.1

Abbildung 1: Help2man bedient sich selbst mit einer Handbuchseite.

Die Überschriften für die Abschnitte und sonstigen Bestandteile bringt Help2man dabei selbst mit und ordnet in der Regel alles korrekt ein. Das setzt allerdings voraus, dass Ihr Programm wenigstens den elementaren Richtlinien des GNU-Projekts folgt [2]. Dazu gehören mindestens eine Mail-Adresse zum Melden von Fehlern und die URL zur Webseite des Projekts.

Details

Das Programm kann wesentlich mehr, als nur die Ausgaben eines anderen Programms in ein anderes Format zu bringen. Möglicherweise wollen Sie in einer Handbuchseite mehr unterbringen als das, was die erwähnten Optionen beim Aufruf hergeben – sei es, um die Ausgabe von --help nicht zu überfrachten oder einfach, um Benutzern im Handbuch ausführlicher Auskunft zu geben. Dazu fügen Sie ganz einfach externe Texte ein. Alles, was Sie sonst noch für wichtig halten, stellen Sie einfach in einer Textdatei mit der Endung .h2m bereit und übergeben den Dateinamen als Argument mit dem Schalter --include an Help2man.

Die simple Textdatei enthält als Überschrift den (englischsprachigen) Namen der Abschnitte in Großbuchstaben, so wie Sie ihn üblicherweise in einer Manpage finden. Danach folgt der Text, den Sie im entsprechenden Abschnitt einfügen wollen (Listing 2, oben). Texte für die Abschnitte NAME und SYNOPSIS hängt Help2man allerdings nicht dort an, sondern ersetzt damit den ursprünglichen Text.

[DESCRIPTION]
Be careful when using help2man unless you know what you do.
/help option string/
Be careful when using help2man unless you know what you do.

Möchten Sie, dass der Text woanders landet, geben Sie mit einem kurzen Auszug aus dem Originaltext des Handbuchs denjenigen Absatz an, nach dem Sie den zusätzlichen Text einschieben möchten. Dazu setzen Sie dieses Textstück einfach zwischen zwei Schrägstriche (Listing 2, unten). Mit ein wenig Perl-Syntax steuern Sie über reguläre Ausdrücke die Position und Art der Einfügung noch präziser. Näheres dazu beschreibt die Manpage zu perlre [1].

Das Texinfo-Format beschränkt sich im Wesentlichen auf den harten Kern der GNU-Projekte und fand bislang anderweitig wenig Anklang. Sofern Ihr eigenes Projekt also keine entsprechenden Dateien mitbringt, sollten Sie den Absatz deaktivieren, der standardmäßig auf das Texinfo-Handbuch verlinkt. Mit dem Schalter -N erledigt Help2man das für Sie. Gibt es doch ein Texinfo-Handbuch, aber unter einem anderen Namen, geben Sie diesen mit -p an.

Zu guter Letzt hat es sich bewährt, die Option --no-discard-stderr mit anzugeben. Unter Umständen landen nämlich Teile der für Help2man wichtigen Infos im Fehlerkanal der Standardausgabe. So retten Sie diese Ausgaben des Programms und führen sie Help2man zu.

Übersetzungen

Lokalisierte Manpages sind bei Programmen für die Kommandozeile längst nicht so weit verbreitet wie bei Handbüchern für GUI-Software. Das Projekt Manpages-de [3] kümmert sich zwar sehr intensiv um die deutschsprachige Lokalisierung, doch als externes Projekt außerhalb der Upstream-Entwicklung der einzelnen Programme kann es hinsichtlich der Aktualität aber nicht immer mithalten. Dabei könnte alles so einfach sein: Bei Bedarf liefert Help2man ohne manuellen Eingriff eines Übersetzers lokalisierte Versionen aus, wenn auch bei manchen Systemen mit Einschränkungen (siehe Kasten “Die Erben von Red Hat”).

Eine solche Lokalisierung setzt voraus, dass für Help2man selbst eine Übersetzung in die Zielsprache existiert [4] und dass die für die Parameter -h und -v relevanten Ausgaben eines Programms bereits übersetzt vorliegen. Letzteres wäre zwar nicht zwingend notwendig, aber dennoch wenig zielführend. Zumindest stellt das sicher, dass eine lückenhafte oder verwaiste Übersetzung Ihres Programms das Erzeugen der Manpage nicht zum Scheitern bringt (Abbildung 2).

Abbildung 2: Eine nicht vorhandene Übersetzung Ihres Programms sorgt nicht dafür, dass Help2man beim Erzeugen der übersetzten Version strauchelt.

Mit dem Schalter -L de (Langfassung: --locale=de) weisen Sie das Programm an, die deutschsprachige Version gleich mitzuliefern. Ebenso verfahren Sie gegebenenfalls mit anderen verfügbaren Sprachen. Dabei müssen Sie Sonderversionen wie de_DE oder es_MX als solche angeben, sofern es eine Basisversion de oder es gibt.

Fazit

Mit dem Gespann aus Help2man und Doclifter [7] (siehe Kasten “Stresstest”) erzielen Sie schnell ordentliche Ergebnisse mit vergleichsweise wenig Aufwand. Ein Allheilmittel stellt das Tool dennoch nicht dar, weswegen sich speziell in den Ökosystemen von Skriptsprachen wie Perl oder Python eigene Systeme für die Dokumentation etabliert haben. 

Abbildung 3: Mit übersetzten Manpages steht Doclifter auf dem Kriegsfuß.

Abbildung 4: Im Hilfebrowser von Gnome sieht eine Handbuchseite gleich viel angenehmer aus.