So erstellen Sie eine Man Page unter Linux

Soll Ihr neues Linux-Programm einen professionellen Eindruck hinterlassen? Erstellen Sie dafür eine Manpage. Wir zeigen Ihnen den einfachsten und schnellsten Weg.

Die Bedeutung von Manpages

Es gibt einen alten Unix-Witz, der besagt, der einzige Befehl, den man wirklich kennen muss, ist „man“. Manpages sind wahre Fundgruben an Wissen und sollten immer die erste Quelle sein, wenn man etwas über einen Befehl lernen möchte.

Wenn Sie Ihrem selbstgeschriebenen Dienstprogramm oder Befehl eine Manpage hinzufügen, verwandeln Sie es von einem nützlichen Code-Fragment in ein vollwertiges Linux-Paket. Benutzer erwarten von einem Programm, das für Linux entwickelt wurde, eine Manpage. Wenn Sie Linux nativ unterstützen, ist eine Manpage quasi obligatorisch, wenn Sie möchten, dass Ihr Programm ernst genommen wird.

Früher wurden Manpages mit einer Sammlung von Formatierungs-Makros geschrieben. Wenn ein Benutzer mit `man` eine Seite aufruft, ruft das System `groff` auf, um die Datei zu lesen und eine formatierte Ausgabe zu erstellen, basierend auf den Makros in der Datei. Die Ausgabe wird dann an `less` weitergeleitet und dort angezeigt.

Sofern Sie nicht häufig Manpages erstellen, ist es eine mühsame Aufgabe, sie manuell mit den Makros zu verfassen. Das Erstellen einer korrekten und gut aussehenden Manpage kann von Ihrem eigentlichen Ziel ablenken – einer prägnanten, aber umfassenden Beschreibung Ihres Befehls.

Konzentrieren Sie sich auf den Inhalt und vermeiden Sie den Kampf mit einer unübersichtlichen Sammlung von Makros.

Pandoc als Lösung

Das Pandoc-Programm ist in der Lage, Markdown-Dateien einzulesen und diese in etwa 40 verschiedene Auszeichnungssprachen und Dokumentformate zu konvertieren, einschließlich Manpages. Es vereinfacht den Prozess des Erstellens von Manpages drastisch und erspart Ihnen das Hantieren mit kryptischen Codes.

Um Pandoc auf Ubuntu zu installieren, können Sie diesen Befehl verwenden:

sudo apt-get install pandoc

Auf Fedora verwenden Sie den folgenden Befehl:

sudo dnf install pandoc

Für Manjaro geben Sie Folgendes ein:

sudo pacman -Syu pandoc

Die Abschnitte einer Manpage

Manpages sind in Abschnitte unterteilt, die einer Standardkonvention folgen. Die benötigten Abschnitte hängen von der Komplexität des beschriebenen Befehls ab.

Die meisten Manpages umfassen mindestens diese Abschnitte:

Name: Der Name des Befehls und eine kurze, einzeilige Beschreibung seiner Funktion.
Synopsis: Eine prägnante Darstellung der Aufrufmöglichkeiten, um das Programm zu starten. Hier werden die Arten der akzeptierten Befehlszeilenparameter angezeigt.
Beschreibung: Eine Erklärung des Befehls oder der Funktion.
Optionen: Eine Liste der Befehlszeilenoptionen und deren Bedeutung.
Beispiele: Einige typische Anwendungsbeispiele.
Exit Values: Die möglichen Rückgabewerte und ihre Bedeutung.
Bugs: Eine Liste bekannter Fehler. Oftmals wird hier ein Link zum Issue Tracker des Projekts hinzugefügt (oder anstelle dessen verwendet).
Autor: Die Person oder die Personen, die den Befehl geschrieben haben.
Copyright: Ihre Urheberrechtsangabe, die üblicherweise auch die Lizenz enthält, unter der das Programm veröffentlicht wird.

Bei komplexeren Manpages finden sich oft auch weitere Abschnitte. Probieren Sie zum Beispiel `man man`. Sie müssen aber nicht alle angeben – nur die, die wirklich relevant sind. Manpages sind nicht der richtige Ort für lange Ausführungen.

Einige weitere Abschnitte, die relativ häufig vorkommen, sind:

Siehe auch: Andere Befehle, die mit dem Thema verwandt sind und für Benutzer nützlich oder relevant sein könnten.
Dateien: Eine Auflistung der im Paket enthaltenen Dateien.
Vorbehalte: Andere Punkte, die man beachten sollte.
Verlauf: Eine Historie der Änderungen am Befehl.

Abschnitte des Handbuchs

Das Linux-Handbuch besteht aus allen Manpages, die in folgende nummerierte Abschnitte unterteilt sind:

1. Ausführbare Programme oder Shell-Befehle.
2. Systemaufrufe: Funktionen, die vom Kernel bereitgestellt werden.
3. Bibliotheksaufrufe: Funktionen in Programmbibliotheken.
4. Spezielle Dateien.
5. Dateiformate und Konventionen, wie zum Beispiel „/etc/passwd“.
6. Spiele.
7. Verschiedenes: Makropakete und Konventionen, wie z.B. groff.
8. Systemverwaltungsbefehle: In der Regel für Root reserviert.
9. Kernel-Routinen: Normalerweise nicht standardmäßig installiert.

Jede Manpage muss angeben, zu welchem Abschnitt sie gehört und auch an der passenden Stelle für diesen Abschnitt abgelegt werden, wie wir später sehen werden. Manpages für Befehle und Dienstprogramme gehören in den ersten Abschnitt.

Das Format einer Manpage

Das Groff-Makroformat ist visuell schwer zu analysieren. Markdown hingegen ist intuitiv und einfach zu handhaben.

Hier sehen Sie eine Manpage im Groff-Format:

Dieselbe Seite in Markdown dargestellt:

Der Vorspann

Die ersten drei Zeilen bilden den sogenannten Vorspann. Diese müssen alle mit einem Prozentzeichen (%) beginnen, ohne vorangestellte Leerzeichen, aber mit einem Leerzeichen danach, gefolgt von:

Die erste Zeile: Sie enthält den Namen des Befehls, gefolgt vom manuellen Abschnitt in Klammern ohne Leerzeichen. Der Name wird zum linken und rechten Abschnitt der Kopfzeile der Manpage. Üblicherweise wird der Befehlsname in Großbuchstaben geschrieben, obwohl viele das nicht tun. Alles, was dem Befehlsnamen und der manuellen Abschnittsnummer folgt, wird zum linken Abschnitt der Fußzeile. Es ist sinnvoll, dies für die Versionsnummer der Software zu verwenden.
Die zweite Zeile: Der/die Name(n) des/der Autors/Autoren. Diese werden in einem automatisch generierten Autorenabschnitt der Manpage angezeigt. Sie müssen keinen Autorenabschnitt hinzufügen – geben Sie einfach hier mindestens einen Namen an.
Die dritte Zeile: Das Datum, das auch zum zentralen Teil der Fußzeile wird.

Name

Abschnitte werden durch Zeilen gekennzeichnet, die mit einem Nummernzeichen (#) beginnen, dem Markup, das in Markdown eine Überschrift kennzeichnet. Das Nummernzeichen (#) muss das erste Zeichen in der Zeile sein, gefolgt von einem Leerzeichen.

Der Namensabschnitt enthält eine kurze einzeilige Beschreibung, die den Namen des Befehls, ein Leerzeichen, einen Bindestrich (-), ein Leerzeichen und dann eine sehr kurze Beschreibung der Funktion des Befehls umfasst.

Zusammenfassung

Die Zusammenfassung beschreibt die verschiedenen Formate, die die Befehlszeile annehmen kann. Dieser Befehl kann ein Suchmuster oder eine Befehlszeilenoption akzeptieren. Die beiden Sternchen (**) auf beiden Seiten des Befehlsnamens bedeuten, dass der Name in der Manpage fett angezeigt wird. Ein einzelnes Sternchen (*) bewirkt, dass die Manpage den Text unterstrichen anzeigt.

Ein Zeilenumbruch führt standardmäßig zu einer Leerzeile. Um einen harten Umbruch ohne Leerzeile zu erzwingen, können Sie einen nachgestellten Backslash (\) verwenden.

Beschreibung

Die Beschreibung erklärt, was der Befehl oder das Programm tut. Die wichtigsten Details sollten prägnant und kurz gefasst dargestellt werden. Denken Sie daran, dass Sie kein Benutzerhandbuch schreiben.

Die Verwendung von zwei Nummernzeichen (##) am Anfang einer Zeile erzeugt eine Überschrift der zweiten Ebene. Verwenden Sie diese, um Ihre Beschreibung in kleinere Abschnitte zu unterteilen.

Optionen

Der Abschnitt „Optionen“ enthält eine Beschreibung aller Befehlszeilenoptionen, die mit dem Befehl verwendet werden können. Üblicherweise werden diese in Fettdruck angezeigt, also fügen Sie zwei Sternchen (**) vor und nach ihnen ein. Die Textbeschreibung der Optionen wird in der nächsten Zeile hinzugefügt und beginnt mit einem Doppelpunkt (:), gefolgt von einem Leerzeichen.

Wenn die Beschreibung kurz genug ist, wird sie in derselben Zeile wie die Befehlszeilenoption angezeigt. Wenn sie zu lang ist, wird sie als eingerückter Absatz unterhalb der Befehlszeilenoption angezeigt.

Beispiele

Der Abschnitt „Beispiele“ enthält eine Auswahl verschiedener Befehlszeilenformate. Beachten Sie, dass die Beschreibungszeilen mit einem Doppelpunkt (:) beginnen, genau wie im Abschnitt „Optionen“.

Exit-Werte

Dieser Abschnitt listet die Rückgabewerte auf, die Ihr Befehl an den aufrufenden Prozess zurücksendet. Dies kann die Shell sein, wenn Sie den Befehl über die Kommandozeile aufgerufen haben, oder ein Skript, wenn Sie ihn über ein Shell-Skript gestartet haben. Auch in diesem Abschnitt beginnen Beschreibungszeilen mit einem Doppelpunkt (:).

Fehler

Der Abschnitt „Bugs“ listet bekannte Fehler, Probleme oder Macken auf, über die Benutzer Bescheid wissen sollten. Bei Open-Source-Projekten ist es üblich, hier einen Link zum Issue Tracker des Projekts anzugeben, um den Status von Fehlern zu überprüfen oder neue zu melden.

Urheberrechte ©

Der Abschnitt Copyright enthält Ihre Urheberrechtserklärung und üblicherweise eine Beschreibung der Lizenz, unter der die Software veröffentlicht wird.

Ein effizienter Workflow

Sie können Ihre Manpage mit Ihrem bevorzugten Editor bearbeiten. Die meisten Editoren mit Syntaxhervorhebung erkennen Markdown und stellen Überschriften sowie Fettdruck und Unterstreichungen farblich hervor. Dies ist eine gute Hilfe, aber um die endgültige Darstellung zu sehen, müssen Sie die Manpage gerendert betrachten.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Öffnen Sie ein Terminalfenster im Verzeichnis, das Ihre Markdown-Datei enthält. Wenn die Datei in Ihrem Editor geöffnet ist, speichern Sie sie regelmäßig auf der Festplatte. Jedes Mal können Sie den folgenden Befehl im Terminal ausführen:

Nachdem Sie diesen Befehl verwendet haben, können Sie die Nach-oben-Taste drücken, um ihn zu wiederholen, und dann die Eingabetaste drücken.

Dieser Befehl ruft Pandoc für die Markdown-Datei auf (hier heißt sie „ms.1.md“):
Die Option -s (eigenständig) generiert eine vollständige Manpage, nicht nur Text im Man-Format.

Die Option -t (Ausgabetyp) mit dem Operator „man“ weist Pandoc an, seine Ausgabe im Man-Format zu erstellen. Wir haben Pandoc nicht angewiesen, die Ausgabe in eine Datei zu schreiben, daher wird sie an stdout gesendet.

Diese Ausgabe wird dann mit der Option -l (lokale Datei) an `man` weitergeleitet. Dies teilt `man` mit, dass es nicht die Man-Datenbank durchsuchen, sondern die benannte Datei öffnen soll. Wenn der Dateiname `—` ist, liest `man` seine Eingabe von stdin.

Das Ergebnis ist, dass Sie in Ihrem Editor speichern und Q drücken können, um `man` zu schließen, wenn es im Terminalfenster ausgeführt wird. Anschließend können Sie die Pfeil-nach-oben-Taste und dann die Eingabetaste drücken, um eine gerenderte Version Ihrer Manpage direkt in `man` anzuzeigen.

Manpage erstellen

pandoc ms.1.md -s -t man -o ms.1

Nachdem Sie Ihre Manpage fertiggestellt haben, müssen Sie eine endgültige Version davon erstellen und sie dann auf Ihrem System installieren. Der folgende Befehl weist Pandoc an, eine Manpage namens „ms.1“ zu generieren:

Dies folgt der Konvention, die Manpage nach dem beschriebenen Befehl zu benennen und die Nummer des Handbuchabschnitts als Dateiendung anzuhängen.

manpath

Dadurch wird eine Datei „ms.1“ erstellt, die unsere neue Manpage darstellt. Wo legen wir sie ab? Dieser Befehl zeigt, wo man nach Manpages sucht:

Die Ergebnisse liefern folgende Informationen:
/usr/share/man: Der Speicherort der Standardbibliothek von Manpages. Wir fügen dieser Bibliothek keine Seiten hinzu.
/usr/local/share/man: Dieser symbolische Link zeigt auf „/usr/local/man“.
/usr/local/man: Hier müssen wir unsere neue Manpage ablegen.

Beachten Sie, dass die verschiedenen Abschnitte des Handbuchs in eigenen Verzeichnissen gespeichert sind: man1, man2, man3 usw. Falls das Verzeichnis für den jeweiligen Abschnitt nicht existiert, müssen wir es erstellen.

sudo mkdir /usr/local/man/man1

Hierfür geben wir Folgendes ein:

sudo cp ms.1 /usr/local/man/man1

Anschließend kopieren wir die Datei „ms.1“ in das richtige Verzeichnis: `man` erwartet, dass Manpages komprimiert sind, daher verwenden wir gzip um sie zu komprimieren.

sudo gzip /usr/local/man/man1/ms.1

Geben Sie Folgendes ein, damit `man` die neue Datei zu seiner Datenbank hinzufügt:

sudo mandb

man ms

Das ist alles! Wir können unsere neue Manpage jetzt wie jede andere aufrufen, indem wir Folgendes eingeben:

Unsere neue Manpage wird gefunden und angezeigt.

Sie sieht aus wie jede andere Manpage, mit fettem, unterstrichenem und eingerücktem Text an den entsprechenden Stellen.

Beschreibungszeilen, die neben die Option passen, die sie beschreiben, werden in derselben Zeile angezeigt. Zu lange Zeilen werden unterhalb der beschriebenen Option angezeigt.

Wir haben außerdem automatisch einen Abschnitt „Autoren“ generiert. Die Fußzeile enthält die Softwareversionsnummer, das Datum und den Befehlsnamen, wie im Vorspann definiert.

Wenn Sie wollen . . .