So erstellen Sie eine Manpage unter Linux

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

Die Mannseiten

In dem alten Unix-Witz steckt ein Körnchen Wahrheit: „The only command you need to know is man .“ Die man enthalten eine Fülle von Informationen und sollten die erste Anlaufstelle sein, wenn Sie mehr über einen Befehl erfahren möchten.

Das Bereitstellen einer man für ein von Ihnen geschriebenes Dienstprogramm oder einen Befehl hebt es von einem nützlichen Stück Code zu einem vollwertigen Linux-Paket auf. Die Leute erwarten, dass eine man für ein Programm bereitgestellt wird, das für Linux geschrieben wurde. Wenn Sie Linux nativ unterstützen, ist eine man obligatorisch, wenn Sie möchten, dass Ihr Programm ernst genommen wird.

In der Vergangenheit wurden die man mit einer Reihe von Formatierungsmakros geschrieben. Wenn Sie man auffordern, eine Seite zu öffnen, ruft es groff auf, um die Datei zu lesen und entsprechend den Makros in der Datei eine formatierte Ausgabe zu erzeugen. Die Ausgabe wird in less geleitet und dann für Sie angezeigt.

Wenn Sie nicht häufig man erstellen, ist das Schreiben einer Manpage und das manuelle Einfügen der Makros harte Arbeit. Das Erstellen einer man , die korrekt analysiert und richtig aussieht, kann Ihr Ziel, eine knappe, aber gründliche Beschreibung Ihres Befehls bereitzustellen, überholen.

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

RELATED: How to Use Man Command von Linux: Versteckte Geheimnisse und Grundlagen

Pandoc zur Rettung

Das pandoc Programm liest Markdown-Dateien und generiert neue in etwa 40 verschiedenen Auszeichnungssprachen und Dokumentformaten, einschließlich dem der man . Es transformiert den Schreibprozess von man vollständig, sodass Sie sich nicht mehr mit Hieroglyphen herumschlagen müssen.

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

 sudo apt-get install pandoc 

Auf Fedora ist der Befehl, den Sie benötigen, der folgende:

 sudo dnf install pandoc 

Geben Sie auf Manjaro Folgendes ein:

 sudo pacman-Syu pandoc 

VERWANDT: So verwenden Sie pandoc zum Konvertieren von Dateien in der Linux-Befehlszeile

Abschnitte einer Man Page

man -Seiten enthalten Abschnitte, die einer Standard-Namenskonvention folgen. Die Abschnitte, die Ihre man benötigt, werden durch die Ausgereiftheit des von Ihnen beschriebenen Befehls bestimmt.

Die meisten Manpages enthalten mindestens diese 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 der Befehlszeilenoptionen und was sie tun.
• Beispiele : Einige Beispiele für den allgemeinen Gebrauch.
• Exit Values : Die möglichen Rückgabecodes 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.
• Copyright : Ihre Copyright-Meldung. Dazu gehört in der Regel auch die Art der Lizenz, unter der das Programm veröffentlicht wird.

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

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

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

Abschnitte des Handbuchs

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

1. Ausführbare Programme: Oder Shell-Befehle.
2. Systemaufrufe: Vom Kernel bereitgestellte Funktionen.
3. Bibliotheksaufrufe: Funktionen innerhalb von Programmbibliotheken.
4. Spezielle Dateien.
5. Dateiformate und Konventionen: Zum Beispiel „/etc/passwd“.
6. Spiele.
7. Sonstiges: Makropakete und Konventionen wie groff .
8. Systemadministrationsbefehle: Normalerweise für root reserviert.
9. Kernel-Routinen: Normalerweise nicht standardmäßig installiert.

Jede man 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 für Befehle und Dienstprogramme gehören in Abschnitt eins.

Das Format einer Manpage

Das groff -Makroformat ist visuell nicht einfach zu analysieren. Im Gegensatz dazu ist Markdown ein Kinderspiel.

Unten ist eine Manpage in groff .

Dieselbe Seite wird unten in Markdown angezeigt.

Vordere Angelegenheit

Die ersten drei Zeilen bilden etwas, das als Front Matter bezeichnet wird. Diese müssen alle mit einem Prozentzeichen ( % ) beginnen, ohne führende Leerzeichen, sondern mit einem dahinter, 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 des man -Headers. Konventionsgemäß wird der Befehlsname in Großbuchstaben geschrieben, obwohl Sie viele finden werden, die dies nicht sind. Alles, was auf den Befehlsnamen und die Abschnittsnummer des Handbuchs folgt, wird zum linken Abschnitt der Fußzeile. Es ist praktisch, dies für die Software-Versionsnummer zu verwenden.
• Die zweite Zeile: Der/die Name(n) des/der Autor(s). Diese werden in einem automatisch generierten Autorenabschnitt der man 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. Dies ist das Markup, das eine Kopfzeile in Markdown anzeigt. Das Nummernzeichen ( #) muss das erste Zeichen in der Zeile sein, gefolgt von einem Leerzeichen.

Der Namensabschnitt enthält einen bissigen Einzeiler, der den Namen des Befehls, ein Leerzeichen, einen Bindestrich ( - ), ein Leerzeichen und dann eine sehr kurze Beschreibung dessen enthält, was der Befehl tut.

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 man fett angezeigt wird. Ein einzelnes Sternchen ( * ) auf beiden Seiten eines Textes bewirkt, dass die man ihn unterstrichen anzeigt.

Standardmäßig folgt auf einen Zeilenumbruch 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 bewirkt. Es sollte die wichtigen Details prägnant abdecken. Denken Sie daran, dass Sie kein Benutzerhandbuch schreiben.

Durch die Verwendung von zwei Nummernzeichen ( ## ) am Anfang einer Zeile wird eine Überschrift der zweiten Ebene erstellt. Sie können diese verwenden, um Ihre Beschreibung in kleinere Stücke zu unterteilen.

Optionen

Der Optionsabschnitt enthält eine Beschreibung aller Befehlszeilenoptionen, die mit dem Befehl verwendet werden können. Konventionsgemäß werden diese fett dargestellt, fügen Sie also zwei Sternchen ( ** ) davor und danach 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 unter der Befehlszeilenoption beginnt.

Beispiele

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

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 sie von der Befehlszeile aufgerufen haben, oder ein Skript, wenn Sie es von einem Shell-Skript gestartet haben. Auch in diesem Abschnitt beginnen wir Beschreibungszeilen mit einem Doppelpunkt ( : ).

Fehler

Der Abschnitt "Fehler" listet bekannte Fehler, 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 Copyright-Abschnitt enthält Ihre Copyright-Erklärung und normalerweise eine Beschreibung des Lizenztyps, unter dem die Software veröffentlicht wird.

Ein effizienter Arbeitsablauf

Sie können Ihre man in Ihrem bevorzugten Editor bearbeiten. Die meisten, die Syntaxhervorhebung unterstützen, kennen Markdown und färben den Text, um Überschriften hervorzuheben, sowie fett und unterstreichen ihn. Das ist großartig, soweit es geht, aber Sie sehen sich keine gerenderte man an, die der wahre Beweis im Pudding ist.

Ö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, wenn Sie dies tun, können Sie den folgenden Befehl im Terminalfenster ausführen:

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

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 von oben nach unten vollständige man , anstatt nur etwas 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 zu suchen. Stattdessen sollte die benannte Datei geöffnet werden. Wenn der Dateiname - ist, nimmt man seine Eingabe von stdin .

Das läuft darauf hinaus, dass Sie aus Ihrem Editor speichern und Q drücken können, um man zu schließen man wenn es im Terminalfenster ausgeführt wird. Dann können Sie den Aufwärtspfeil drücken, gefolgt von der Eingabetaste, um eine gerenderte Version Ihrer man direkt in man .

VERWANDT: Was sind stdin, stdout und stderr unter Linux?

Erstellung Ihrer Manpage

Nachdem Sie Ihre man 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 man mit dem Namen „ms.1“ zu erstellen:

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

Dies folgt der Konvention, die man nach dem Befehl zu benennen, den sie beschreibt, und die Abschnittsnummer des Handbuchs anzuhängen, als wäre es eine Dateierweiterung.

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

 Menschenpfad 

Die Ergebnisse geben uns die folgenden Informationen:

• /usr/share/man: Der Speicherort der Standardbibliothek von man . 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 man platzieren.

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

Dazu geben wir Folgendes ein:

 sudo mkdir /usr/local/man/man1

Anschließend kopieren wir die Datei „ms.1“ in das richtige Verzeichnis:

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

man erwartet, dass die man komprimiert sind, also 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 

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

 Mann ms 

Unsere neue man wird gefunden und angezeigt.

Sie sieht genauso aus wie jede andere man , mit fettgedrucktem, unterstrichenem und eingerücktem Text an den entsprechenden Stellen.

Beschreibungszeilen, die neben die Option passen, die sie beschreiben, erscheinen in derselben Zeile. Zeilen, die zu lang sind, werden unter der Option angezeigt, die sie beschreiben.

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

Wenn Sie wollen . . .

Sobald pandoc Ihre man erstellt hat, können Sie die Datei auch direkt im groff -Makroformat bearbeiten, bevor Sie sie in das man -Verzeichnis verschieben und gzip .