Linux-Lexikon — Anatomie einer Manpage
Veröffentlicht: 2016-11-01
Kurze Bytes: Software-Manpages und -Dokumentation können für jeden Anfänger dick und schwierig genug sein, ohne die kryptischen Konventionen, die mit jeder Art von Klammern und Klammern geschnürt sind. Hier werden wir versuchen, die Komplexität von Linux-Manpages abzumildern und sie leichter verständlich zu machen.
NAME
Zuerst ist die Namensüberschrift, und das fasst es ungefähr zusammen. Dieser Abschnitt enthält den Namen des Dienstprogramms sowie eine kurze Beschreibung.
ZUSAMMENFASSUNG
Es gibt von Manpage zu Manpage unterschiedliche Grade der Lesbarkeit, aber eines ist sicher, der schwierigste Teil ist normalerweise das Entschlüsseln einer haarigen Zusammenfassung. Es gibt mehrere Konventionen für die Angabe der erforderlichen Informationen für einen bestimmten Befehl. Diese Konventionen bestehen aus verschiedenen Klammern und runden Klammern sowie anderen Notationsformen. All diese unterschiedlichen Konventionen können für einen Anfänger extrem verwirrend sein und für jemanden, der Erfahrung hat, aber nicht in der Kunst der Handbücher versiert ist, immer noch entmutigend sein. Im Folgenden werden wir das Kauderwelsch in verdauliche Regeln herunterbrechen.
| ermutigt | Geben Sie genau wie gezeigt ein. |
| kursiv oder unterstrichen | Durch entsprechendes Argument ersetzen. |
| [-abcxyz] | Alle Flags in eckigen Klammern sind optional. |
| -a | -B | Durch Pipe getrennte Optionen können nicht zusammen verwendet werden. |
| <obligatorisch> | Obligatorisches Argument, das normalerweise in Optionsbeschreibungen zu finden ist. |
| {ja Nein} | Begrenzte Optionen, nur die angegebenen funktionieren. |
| … | Argumente gefolgt von Auslassungspunkten können wiederholt werden. |
Diese Regeln sind ziemlich einfach, aber sie werden schwieriger und sogar einschüchternd, wenn sie in langen Funktionsdefinitionen verwendet werden, insbesondere wenn sie verschachtelt sind. Also werfen wir einen Blick auf einige Verschachtelungen unten, um das aufzubauen, was wir zerlegt haben.
tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG …]
Der tar- Befehl hat viele Optionen. Wir sehen den Namen des tar-Befehls in Fettdruck, da er wie gezeigt eingegeben werden sollte. Dann sehen wir die geöffneten geschweiften Klammern mit durch Rohre getrennten Optionen, die darauf hinweisen, dass wir auf diese beschränkt sind und nur eine auswählen müssen. Als nächstes kommen die optionalen Flags, wir können eine beliebige Zahl verwenden, aber sie funktionieren möglicherweise nicht alle zusammen. Wenn Sie weiter in der Manpage lesen, werden Sie Licht auf mögliche Konflikte der Optionen werfen. Und schließlich haben wir das wiederholbare Argument, im Fall von tar dies für die Datei(en), mit denen Sie arbeiten.
su [Optionen] [-] [ Benutzer [ Argument …]]
Auch hier sehen wir su fett, weil es der Name des Befehls ist. Zweitens sehen wir, dass eigentlich keine Flags angegeben sind, sondern dass sie optional sind. Drittens gibt es ein einzelnes Flag, das angegeben wird, aber auch es ist optional. Zuletzt sehen wir ein optionales Argument, das innerhalb eines optionalen Arguments wiederholbar ist. Was früher sehr mysteriös aussah, macht jetzt mehr Sinn.
whois [{-h|–host } HOST ] [{-p|–port} PORT ] [-abBcdGHKlLmMrRx] [-g SOURCE:FIRST-LAST ] [-i ATTR [, ATTR ]…] [-s SOURCE [, SOURCE ]…] [-T TYPE [, TYPE ]…] [–verbose] OBJEKT
Diese ist besonders dicht. Kopieren Sie es in Ihren bevorzugten Texteditor und fügen Sie dort einige zusätzliche Leerzeichen hinzu, wenn es Ihnen beim Lesen hilft. Nachdem Sie darüber gescannt haben, sollten Sie beginnen, ein paar Muster zu sehen. Die Host- und Port-Teile verwenden die gleiche Formatierung für die Kurz- und Langform der Option, gefolgt vom Argument für diese Option, obwohl beide selbst optional sind. Dann sehen wir die Zeichenfolge der optionalen Flags. Das nächste Stück über Quellen von Anfang bis Ende ist die Syntax, die von whois erwartet wird, was später in der Manpage erklärt wird. Jetzt sehen wir dieses Triplet optionaler Flags, die entweder ein einzelnes Argument oder optionale, sich wiederholende Argumente annehmen. Dies ist die Art der Zusammenfügung der Konventionen, die zunächst sehr schwer vollständig zu verstehen sein kann. Schließlich gibt es die ausführliche Option und das Objekt (der Host/die Domäne).
Und so liest man eine Manpage-Zusammenfassung. Es gibt noch ein paar andere Konventionen, aber sie sind viel zu obskur, um sie in diesem Artikel zu behandeln.
BEZEICHNUNG
Hier wird im Allgemeinen die beabsichtigte Verwendung des Programms oder Dienstprogramms beschrieben. Einige Handbücher werden unter dieser Überschrift viel ausführlicher sein als andere.
OPTIONEN
Erinnern Sie sich an all diese Flags und verschiedenen Argumente, die optional oder obligatorisch sein können? Hier werden sie alle erklärt. Hier gibt es normalerweise gute Informationen, und oft finden Sie dort die <argument>-Konvention, die angibt, dass ein bestimmtes Flag ein entsprechendes Argument erfordert. Manchmal werden Sie feststellen, dass die Optionen im Beschreibungsteil stehen, weil es keine feste Regel gibt, die Handbuchseiten definiert, sondern nur Konventionen und den Willen, sich an die Standards zu halten.
BEISPIELE
Dies ist eines der praktischsten Teile, das leider nicht in allen Handbüchern enthalten ist. Sie werden auch feststellen, dass die Menge an Informationen und die Anzahl der Beispiele erheblich variieren und nicht alle Beispiele tatsächlich bei der Verwendung des Befehls helfen.
Außerdem finden Sie regelmäßig Abschnitte für den Autor, Copyright-Informationen, Fehlerberichte und siehe auch (apropos).
Darüber hinaus gibt es die formal definierten Abschnitte von Manpages, wie unten definiert.
| 1 | Ausführbare Programme oder Shell-Befehle |
| 2 | Systemaufrufe (vom Kernel bereitgestellte Funktionen) |
| 3 | Bibliotheksaufrufe (Funktionen innerhalb von Programmbibliotheken) |
| 4 | Spezielle Dateien (normalerweise in /dev zu finden) |
| 5 | Dateiformate und Konventionen zB /etc/passwd |
| 6 | Spiele |
| 7 | Verschiedenes (einschließlich Makropakete und Konventionen), zB man(7), groff(7) |
| 8 | Systemadministrationsbefehle (normalerweise nur für root) |
| 9 | Kernel-Routinen (normalerweise nicht unter Linux zu finden) |
Viele Befehle haben keine Handbücher in mehr als einem Abschnitt, aber für diejenigen, die dies tun, oder für einige, die möglicherweise mehrdeutig benannt sind, können Sie den Abschnitt wie im folgenden Beispiel angeben.
Befehle sind nicht die einzigen Dinge, die Handbücher haben, wie Sie den verfügbaren Abschnitten entnehmen können. Systemaufrufe, Konfigurationsdateien und spezielle Geräte können ebenso wahrscheinlich eine entsprechende Manpage haben. Die Menge an Informationen zu einer typischen Linux-Installation allein in Manpages ist erstaunlich, und das Gleiche gilt für andere Open-Source-UNIX-ähnliche Betriebssysteme.
Wenn Sie feststellen, dass die Manpage nicht ausreicht und Sie einen Befehl immer noch nicht verstehen, schauen Sie immer online nach, da viele Leute ausführlichere Erklärungen zu bestimmten Tools anbieten, aber auch viele Distributionen ihre eigenen Manpages für verschiedene Softwarepakete haben. Wenn Sie festgestellt haben, dass Sie mit einer Software vertraut sind, aber immer noch das Gefühl haben, dass das Handbuch fehlt, können Sie jederzeit einen Beitrag leisten, indem Sie Ihr eigenes schreiben und es für das jeweilige Projekt einreichen. Die Dokumentation ist oft der am meisten vernachlässigte Teil von Softwareprojekten. Selbst wenn Sie keinen Code schreiben können, können Sie Handbücher, Wiki-Artikel und Tutorials schreiben, um anderen zu helfen.
Jetzt, da Sie die Anatomie einer Manpage kennen, haben Sie keine Entschuldigung mehr als RTFM (und das ist das kostenlose Handbuch für diejenigen unter 18 Jahren) ;)
Lesen Sie auch: Linux-Lexikon: Verwenden Sie den Watch-Befehl, um alle X Sekunden einen Befehl auszuführen