So erstellen Sie eine Man Page unter Linux

Möchten Sie, dass Ihr neues Linux-Programm professionell aussieht? Geben Sie ihm eine Manpage. Wir zeigen Ihnen den einfachsten und schnellsten Weg.

Die Mannseiten

In dem alten Unix-Witz steckt ein Körnchen Wahrheit: einziger Befehl den du brauchst zu wissen ist ein Mensch.“ Die Manpages enthalten eine Fülle von Wissen und sollten die erste Anlaufstelle sein, wenn Sie etwas über einen Befehl erfahren möchten.

Wenn Sie eine Manpage für ein von Ihnen geschriebenes Dienstprogramm oder einen Befehl bereitstellen, wird es von einem nützlichen Codestück zu einem vollständig geformten Linux-Paket. Die Leute erwarten, dass eine Manpage für ein Programm bereitgestellt wird, das für Linux geschrieben wurde. Wenn Sie Linux nativ unterstützen, ist eine Manpage obligatorisch, wenn Sie möchten, dass Ihr Programm ernst genommen wird.

In der Vergangenheit wurden die Manpages mit einer Reihe von Formatierungsmakros geschrieben. Wenn du den Menschen aufrufst, eine Seite zu öffnen, ruft er groff auf, um Lesen Sie die Datei und generieren Sie eine formatierte Ausgabe, entsprechend den Makros in der Datei. Die Ausgabe wird in weniger geleitet, und dann für dich angezeigt.

Sofern Sie nicht häufig Manpages erstellen, ist das Schreiben einer und das manuelle Einfügen der Makros harte Arbeit. Das Erstellen einer Manpage, die korrekt geparst und richtig aussieht, kann Ihr Ziel, eine prägnante, aber gründliche Beschreibung Ihres Befehls bereitzustellen, übertreffen.

Sie sollten sich auf Ihre Inhalte konzentrieren und nicht mit einer obskuren Reihe von Makros kämpfen.

Pandoc zur Rettung

Der Pandoc-Programm liest Markdown-Dateien und generiert neue in etwa 40 verschiedenen Markup-Sprachen und Dokumentformaten, einschließlich der Manpage. Es verändert den Schreibprozess von Manpages vollständig, sodass Sie sich nicht mit Hieroglyphen herumschlagen müssen.

Um zu beginnen, können Sie pandoc auf Ubuntu mit diesem Befehl installieren:

sudo apt-get install pandoc

Auf Fedora benötigen Sie den folgenden Befehl:

sudo dnf install pandoc

Geben Sie auf Manjaro Folgendes ein:

sudo pacman -Syu pandoc

Abschnitte einer Mannseite

man-Seiten enthalten Abschnitte, die einer Standardnamenskonvention folgen. Die Abschnitte, die Ihre Manpage benötigt, werden durch die Komplexität des von Ihnen beschriebenen Befehls bestimmt.

Die meisten Manpages enthalten mindestens die folgenden Abschnitte:

Name: Der Name des Befehls und ein prägnanter Einzeiler, der seine Funktion beschreibt.
Synopsis: Eine knappe Beschreibung der Aufrufe, die jemand verwenden kann, um das Programm zu starten. Diese zeigen die Typen der akzeptierten Befehlszeilenparameter.
Beschreibung: Eine Beschreibung des Befehls oder der Funktion.
Optionen: Eine Liste von Befehlszeilenoptionen und deren Funktion.
Beispiele: Einige Beispiele für die allgemeine Verwendung.
Exit Values: Die möglichen Rückkehrcodes und ihre Bedeutung.
Bugs: Eine Liste bekannter Bugs und Macken. Manchmal wird dies durch einen Link zum Issue Tracker für das Projekt ergänzt (oder ersetzt).
Autor: Die Person oder Personen, die den Befehl geschrieben haben.
Urheberrecht: Ihre Urheberrechtsnachricht. Dazu gehört in der Regel auch die Art der Lizenz, unter der das Programm veröffentlicht wird.

Wenn Sie einige der komplizierteren Manpages durchsehen, werden Sie feststellen, dass es auch viele andere Abschnitte gibt. Versuchen Sie es zum Beispiel mit Mann Mann. Sie müssen jedoch nicht alle angeben – nur die, die Sie wirklich brauchen. Manpages sind kein Platz für Wortgefecht.

Einige andere Abschnitte, die Sie relativ häufig sehen werden, sind:

Siehe auch: Andere Befehle im Zusammenhang mit dem Thema, die einige nützlich oder relevant finden würden.
Dateien: Eine Liste der im Paket enthaltenen Dateien.
Vorbehalte: Andere Punkte, die Sie kennen oder beachten sollten.
Verlauf: Ein Änderungsverlauf für den Befehl.

Abschnitte des Handbuchs

Das Linux-Handbuch besteht aus allen man-Seiten, die dann in diese nummerierten Abschnitte unterteilt sind:

Ausführbare Programme: Oder Shell-Befehle.
Systemaufrufe: Vom Kernel bereitgestellte Funktionen.
Bibliotheksaufrufe: Funktionen innerhalb von Programmbibliotheken.
Spezielle Dateien.
Dateiformate und Konventionen: Zum Beispiel „/etc/passwd“.
Spiele.
Sonstiges: Makropakete und Konventionen, wie z. B. groff.
Systemverwaltungsbefehle: Normalerweise für Root reserviert.
Kernel-Routinen: Normalerweise nicht standardmäßig installiert.

Jede Manpage muss angeben, zu welchem ​​Abschnitt sie gehört, und sie muss auch an der entsprechenden Stelle für diesen Abschnitt gespeichert werden, wie wir später sehen werden. Die man-Seiten für Befehle und Dienstprogramme gehören in den ersten Abschnitt.

Das Format einer man Page

Das Groff-Makroformat ist nicht einfach visuell zu analysieren. Im Gegensatz dazu ist der Abschlag ein Kinderspiel.

Unten ist eine Manpage in groff.

Dieselbe Seite wird unten im Markdown angezeigt.

Vordersache

Die ersten drei Zeilen bilden eine sogenannte Frontmaterie. Diese müssen alle mit einem Prozentzeichen (%) beginnen, ohne führende Leerzeichen, aber eins danach, gefolgt von:

Die erste Zeile: 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. Konventionell wird der Befehlsname in Großbuchstaben geschrieben, obwohl Sie viele finden, die dies nicht sind. Alles, was auf den Befehlsnamen und die manuelle Abschnittsnummer folgt, wird zum linken Abschnitt der Fußzeile. Es ist praktisch, dies für die Softwareversionsnummer zu verwenden.
Die zweite Zeile: Der/die Name(n) des/der Autor(s). Diese werden in einem automatisch generierten Autorenbereich der Manpage angezeigt. Sie müssen keinen Abschnitt „Autoren“ hinzufügen – geben Sie hier einfach mindestens einen Namen ein.
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 eine Kopfzeile im Markdown anzeigt. Das Nummernzeichen (#) muss das erste Zeichen in der Zeile sein, gefolgt von einem Leerzeichen.

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

Zusammenfassung

Die Zusammenfassung enthält 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 auf der Manpage fett angezeigt wird. Ein einzelnes Sternchen

auf beiden Seiten eines Textes bewirkt, dass die Manpage ihn unterstrichen anzeigt.

Auf einen Zeilenumbruch folgt standardmäßig eine 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. Es sollte die wichtigen Details kurz und bündig abdecken. Denken Sie daran, dass Sie kein Benutzerhandbuch schreiben.

Die Verwendung von zwei Nummernzeichen (##) am Anfang einer Zeile erzeugt eine Überschrift der zweiten Ebene. Sie können diese verwenden, 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. Konventionell werden diese in Fettdruck angezeigt, fügen Sie also zwei Sternchen (**) vor und nach ihnen ein. Fügen Sie die Textbeschreibung der Optionen in die nächste Zeile ein und beginnen Sie mit einem Doppelpunkt (:), gefolgt von einem Leerzeichen.

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

Beispiele

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

Exit-Werte

In diesem Abschnitt werden die Rückgabewerte aufgelistet, die Ihr Befehl an den aufrufenden Prozess zurücksendet. Dies kann die Shell sein, wenn Sie sie über die Befehlszeile aufgerufen haben, oder ein Skript, wenn Sie es über ein Shell-Skript gestartet haben. Auch in diesem Abschnitt beginnen wir Beschreibungszeilen mit einem Doppelpunkt (:).

Fehler

Der Abschnitt Bugs listet bekannte Bugs, Fallstricke oder Macken auf, über die die Leute Bescheid wissen müssen. Bei Open-Source-Projekten ist es üblich, hier einen Link zum Issue Tracker des Projekts einzufügen, um den Status von Fehlern zu überprüfen oder neue zu melden.

Urheberrechte ©

Der Abschnitt zum Copyright enthält Ihre Copyright-Erklärung und normalerweise eine Beschreibung des Lizenztyps, unter dem die Software veröffentlicht wird.

Ein effizienter Workflow

Sie können Ihre Manpage in Ihrem bevorzugten Editor bearbeiten. Die meisten, die Syntaxhervorhebungen unterstützen, werden sich des Hervorhebens bewusst sein und den Text einfärben, um Überschriften hervorzuheben, sowie ihn fett und unterstreichen. Soweit es geht, ist das großartig, aber Sie sehen sich keine gerenderte Manpage an, die der wahre Beweis in der Sache ist.

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

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

Nachdem Sie diesen Befehl verwendet haben, können Sie den Aufwärtspfeil drücken, um ihn zu wiederholen, und dann die Eingabetaste drücken.

Dieser Befehl ruft auch pandoc für die Markdown-Datei auf (hier heißt sie „ms.1.md“):
Die Option -s (eigenständig) generiert eine komplette Manpage von oben nach unten und nicht nur einen Text im man-Format.

Die Option -t (Ausgabetyp) mit dem Operator „man“ weist pandoc an, seine Ausgabe im man-Format zu generieren. Wir haben pandoc nicht angewiesen, seine Ausgabe an eine Datei zu senden, also wird sie an stdout gesendet.

Wir leiten diese Ausgabe auch mit der Option -l (lokale Datei) an man weiter. Es weist man an, nicht die man-Datenbank zu durchsuchen, um nach der man-Seite zu suchen. Stattdessen sollte es die benannte Datei öffnen. Wenn der Dateiname – ist, nimmt man seine Eingabe von stdin.

Worauf dies hinausläuft, 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. Dann können Sie den Aufwärtspfeil und dann die Eingabetaste drücken, um eine gerenderte Version Ihrer Manpage direkt in man anzuzeigen.

Erstellen Sie Ihre Man Page

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 anzuhängen, als ob es eine Dateierweiterung wäre.

manpath

Dadurch wird eine „ms.1“-Datei erstellt, die unsere neue Manpage ist. Wo legen wir es hin? Dieser Befehl sagt uns, wo man nach man-Seiten sucht:

Die Ergebnisse geben uns 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 platzieren.

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

sudo mkdir /usr/local/man/man1

Dazu 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 die Manpages komprimiert sind, also verwenden wir gzipum es zu komprimieren

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

:

sudo mandb

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

man ms

Das ist es! Wir können jetzt unsere neue Manpage 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 von ihnen beschriebene Option passen, werden in derselben Zeile angezeigt. Zeilen, die zu lang sind, werden unter der beschriebenen Option angezeigt.

Wir haben auch automatisch einen Abschnitt „Autoren“ generiert. Die Fußzeile enthält auch die Softwareversionsnummer, das Datum und den Befehlsnamen, wie in der Einleitung definiert.

Wenn Sie wollen . . .