So erstellen Sie eine Man Page unter Linux

Fatmawati Achmad Zaenuri/Shutterstock

Möchten Sie, dass Ihr neues Linux-Programm professionell aussieht? Geben Sie es man Seite. 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 man.“ Die man Seiten enthalten eine Fülle von Wissen, und sie sollten der erste Ort sein, an dem Sie sich umsehen, wenn Sie etwas über einen Befehl erfahren möchten.

Bereitstellung eines man Seite für ein Dienstprogramm oder einen Befehl, den Sie geschrieben haben, hebt es von einem nützlichen Codestück zu einem vollständig geformten Linux-Paket. Die Leute erwarten ein man Seite für ein Programm bereitzustellen, das für Linux geschrieben wurde. Wenn Sie Linux nativ unterstützen, a man Seite ist obligatorisch, wenn Sie möchten, dass Ihr Programm ernst genommen wird.

Historisch gesehen man Seiten wurden mit einer Reihe von Formatierungsmakros geschrieben. Wenn du anrufst man um eine Seite zu öffnen, ruft es auf groff zu Lesen Sie die Datei und generieren Sie eine formatierte Ausgabe, entsprechend den Makros in der Datei. Die Ausgabe wird in geleitet less, und dann für dich angezeigt.

Es sei denn, Sie erstellen man Seiten häufig, ist das Schreiben einer und das manuelle Einfügen der Makros harte Arbeit. Der Akt des Erstellens von a man Seite, die richtig geparst und richtig aussieht, kann Ihr Ziel übertreffen, eine prägnante, aber gründliche Beschreibung Ihres Befehls bereitzustellen.

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

Pandoc zur Rettung

Die pandoc Programm liest Markdown-Dateien und generiert neue in etwa 40 verschiedenen Markup-Sprachen und Dokumentformaten, einschließlich des man Seite. Es verwandelt die total man Seitenschreibprozess, damit Sie nicht mit Hieroglyphen ringen müssen.

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

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 deine man Die Anforderungen an die Seite werden durch die Komplexität des von Ihnen beschriebenen Befehls bestimmt.

Die meisten man-Seiten enthalten mindestens die folgenden Abschnitte:

• Name: Der Name des Befehls und ein prägnanter Einzeiler, der seine Funktion beschreibt.
• Zusammenfassung: 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-Werte: Die möglichen Rückkehrcodes und ihre Bedeutung.
• Fehler: Eine Liste bekannter Fehler 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.
• Urheberrechte ©: 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 durchsehen man Sie werden sehen, dass es auch viele andere Abschnitte gibt. Versuchen Sie es zum Beispiel man man. Sie müssen jedoch nicht alle angeben – nur die, die Sie wirklich brauchen. man Seiten sind kein Platz für Wortschatz.

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

• Siehe auch: Andere Befehle, die sich auf das Thema beziehen, würden einige nützlich oder relevant finden.
• Dateien: Eine Liste der im Paket enthaltenen Dateien.
• Vorbehalte: Andere Punkte, die Sie kennen oder beachten sollten.
• Geschichte: Eine Änderungshistorie für den Befehl.

Abschnitte des Handbuchs

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

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. Sonstig: Makropakete und Konventionen, wie z groff.
8. Befehle der Systemverwaltung: Normalerweise für Root reserviert.
9. Kernel-Routinen: Normalerweise nicht standardmäßig installiert.

Jeden man page 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 Abschnitt eins.

Das Format einer man Page

Die 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 etwas namens . Diese müssen alle mit einem Prozentzeichen (%), 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 des man Kopfzeile. 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 des man Seite. 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 Linien gekennzeichnet, die mit einem Nummernzeichen beginnen (#), das ist das Markup, das einen Header im Markdown angibt. Das Nummernzeichen (#) muss das erste Zeichen in der Zeile sein, gefolgt von einem Leerzeichen.

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

Zusammenfassung

Die Synopse 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 bedeutet, dass der Name auf dem fett angezeigt wird man Seite. Ein einzelnes Sternchen (*) auf beiden Seiten eines Textes verursacht das man Seite, um sie unterstrichen anzuzeigen.

Auf einen Zeilenumbruch folgt standardmäßig eine Leerzeile. Um einen harten Umbruch ohne Leerzeile zu erzwingen, können Sie einen nachgestellten Backslash ().

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, Sie schreiben kein Benutzerhandbuch.

Mit zwei Nummernzeichen (##) am Anfang einer Zeile erstellt 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 fett dargestellt, also schließen Sie zwei Sternchen ein (**) vor und nach ihnen. Fügen Sie die Textbeschreibung der Optionen in die nächste Zeile ein und beginnen Sie sie mit einem Doppelpunkt (:), gefolgt von einem Leerzeichen.

Wenn die Beschreibung kurz genug ist, man wird es in derselben Zeile wie die Befehlszeilenoption anzeigen. 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 (:), 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 von einem aus gestartet haben Shell-Skript. Wir beginnen Beschreibungszeilen mit einem Doppelpunkt (:) auch in diesem Abschnitt.

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 . bearbeiten man Seite in Ihrem bevorzugten Editor. 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 du siehst kein gerendertes an man Seite, 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 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 . auf pandoc auf der Markdown-Datei (hier heißt sie „ms.1.md“):

• Die -s (Standalone)-Option generiert ein komplettes von oben nach unten man Seite, und nicht nur ein Text in man Format.
• Die -t (Ausgabetyp) Option mit dem Operator „man“ sagt pandoc seine Ausgabe in . erzeugen man Format. Wir haben es nicht erzählt pandoc um seine Ausgabe an eine Datei zu senden, damit sie gesendet wird an stdout.

Wir leiten diese Ausgabe auch in man mit dem -l (lokale Datei) Option. Es sagt man nicht durchsuchen man Datenbank auf der Suche nach dem man Seite. Stattdessen sollte es die benannte Datei öffnen. Wenn der Dateiname . ist -, man nimmt seinen Input von stdin.

Worauf es hinausläuft, ist, dass Sie in Ihrem Editor speichern und zum Schließen Q drücken können man wenn es im Terminalfenster läuft. Dann können Sie den Aufwärtspfeil und dann die Eingabetaste drücken, um eine gerenderte Version Ihres man Seite, rechts drin man.

Erstellen Sie Ihre Man Page

Nachdem Sie Ihre man Seite müssen Sie eine endgültige Version davon erstellen und sie dann auf Ihrem System installieren. Der folgende Befehl sagt pandoc a . erzeugen man Seite mit dem Namen „ms.1“:

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

Dies folgt der Konvention der Benennung der man Seite nach dem Befehl, den es beschreibt, und fügen Sie die Nummer des Handbuchabschnitts an, als ob es eine Dateierweiterung wäre.

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

manpath

Die Ergebnisse geben uns folgende Informationen:

• /usr/share/man: Der Speicherort der Standardbibliothek von man Seiten. Wir fügen dieser Bibliothek keine Seiten hinzu.
• /usr/local/share/man: Dieser symbolische Link verweist auf „/usr/local/man“.
• /usr/local/man: Hier müssen wir unser neues platzieren man Seite.

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.

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 die man Seiten komprimiert werden, also verwenden wir gzip um es zu komprimieren:

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

zu machen man Fügen Sie die neue Datei zu ihrer Datenbank hinzu, und geben Sie Folgendes ein:

sudo mandb

Das ist es! Wir können jetzt unser neues anrufen man Seite genauso wie jede andere, indem Sie Folgendes eingeben:

man ms

Unser neuer man Seite gefunden und angezeigt.

Es sieht aus wie jedes andere man Seite 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 du möchtest . . .

Wenn pandoc hat deine erstellt man Seite können Sie die Datei auch direkt im groff Makro-Format, bevor Sie es in das man Seitenverzeichnis und gzip es.