Aus LinuxUser 04/2018

Mit Help2man Manpages bauen

© Theromb, 123RF

Wandlungsfähig

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).

Listing 1

$ 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.
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.

Listing 2

[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“).

DIESEN ARTIKEL ALS PDF KAUFEN
EXPRESS-KAUF ALS PDFUmfang: 4 HeftseitenPreis €0,99
(inkl. 19% MwSt.)
KAUFEN
LinuxUser 04/2018 KAUFEN
EINZELNE AUSGABE Print-Ausgaben Digitale Ausgaben
ABONNEMENTS Print-Abos Digitales Abo
TABLET & SMARTPHONE APPS
Deutschland

Hinterlasse einen Kommentar

  E-Mail Benachrichtigung  
Benachrichtige mich zu:

Hallo zusammen,

in diesem Umfeld sollte das Engagement für quelloffene Software auch durch viele Unternehmen und Organisationen stärker gefördert werden.

Insbesondere da die Fernsehanstalten mit versteckten oder sichtbaren Kameras in u.a. Fernsehgeräten die Bevölkerung wie in „Big Bang Theorie“ oder „Der Prinz von Bel Air“ überwachen. Das soll für alle dann wohl wie bei den Borg aus „Star Trek: Der Erste Kontakt“ oder der „Truman Show“ werden.

Also besser auf Fernseher usw. verzichten.

Selbst die Bundesnetzagentur warnt schon seit Jahren davor.

Bundesnetzagentur sagt verbotenen Spionagekameras den Kampf an

Webseite:
http://www.bundesnetzagentur.de

Abgesehen von der Tatsache, dass dieser recht wirre Kommentar rein gar nichts mit dem Artikel zu tun hat, handelt es sich hier um ein klassisches Beispiel für Fake News.

Tatsächlich warnt die Bundesnetzagentur keineswegs vor verwanzten TV-Geräten, sondern vor USB-Kameras, die als Gegenstände des täglichen Gebrauchs getarnt sind, wie Kugelschreiber, Uhren, Rauchmelder, Lampen oder Ähnliches. Den Originaltext finden Sie hier:
https://www.bundesnetzagentur.de/SharedDocs/Pressemitteilungen/DE/2016/160425_cam.html

Wir lassen den Kommentar hier trotzdem stehen, weil uns die Löschung von Beiträgen widerstrebt, solange sie keine justiziablen oder kommerziellen Inhalte haben.

Die Redaktion