Ich war lange Zeit ein chronischer Googler, wobei doch die Antworten auf viele meiner Fragen bereits auf meinem Computer gespeichert sind. Heute trivialisieren Tools wie AI die Suche noch mehr, doch auch sie beruhen (unter anderem) auf Informationen aus den Manpages. Vor einiger Zeit fühlte ich das Bedürfnis, mir die Manpages genauer anzuschauen. Hoffentlich kann euch dieser Artikel sie ebenfalls etwas näher bringen (PS: cool-retro-term ist nicht mein Standard Terminal Emulator, das Bild sollte lediglich für Aufmerksamkeit sorgen).

Manpages

Die Manpages (englisch manual, Handbuch), aufrufbar mit dem Befehl man, sind eine Kollektion von Bedienungsanleitungen von Software auf Linux Systemen. man formatiert die gewünschte Seite und übergibt sie an einen Pager (standardmässig das Programm less, historisch auch more) für die Anzeige im Terminal. Ein benutzerdefiniertes Programm kann in der PAGER bzw. MANPAGER Umgebungsvariable definiert werden. ` kann z.B. ein Befehl, Gerät, Dateiname oder Name einer Bibliothek sein.man man` für eine detaillierte Beschreibung der Manpages.

Konventionelle Namen der einzelnen Abschnitte heissen: NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, STANDARDS, NOTES, BUGS, EXAMPLE, AUTHORS, und SEE ALSO.

Wichtig: Die Manpages sind ausgereift, stellen jedoch nur einen Teil der vollständigen Dokumentation dar. Sie eignen sich allen voran für die Dokumentation von Befehlen und Standarddateien/Bibliotheken. Viele Informationen sind in den Wikis der jeweiligen Distros bzw. Entwickler der Tools hinterlegt. Bsp.: vim. Manpage erklärt die CLI Argumente, aber nicht die Bedienung von vim.

Manpage-Syntaxkonvention der SYNOPSIS

Der Zweck der SYNOPSIS ist die formale Beschreibung der Aufrufsyntax eines Programms ohne semantische Erklärung. Sie zeigt ausschließlich Struktur und Argumentreihenfolge. Die Darstellungsnotation der SYNOPSIS in Manpages ist eine historisch gewachsene UNIX-Dokumentationskonvention, die von BSD, System V und später vom GNU Projekt übernommen und weitergeführt wurde. POSIX hat nur gewisse Elemente der Notation standardisiert.

Frühe UNIX Konvention war es, zuerst alle Optionen und erst im Anschluss die Positionsparameter anzugeben. Heute ist dies nicht mehr zwingend; moderne Tools akzeptieren oft eine flexible Reihenfolge.

Was sind Positionsparameter?: Ein Positionsparameter ist ein Parameter, dessen Bedeutung sich aus seiner bestimmten Position in der Argumentliste ergibt. Im Beispiel unten sind FILE und [expression] Positionsparameter, da kein anderes syntaktisches Merkmal existiert, an dem ihre Bedeutung erkenntlich ist (im Gegensatz zu Optionen, die mit einem - eingeleitet werden).

Technisch gesehen übergibt die Shell sowohl Positionsparameter als auch Optionen als Argumente in einer bestimmten Reihenfolge an das Programm (über argv[]), konzeptionell unterscheidet man sie jedoch.

Aus man man:

• fett: 1 zu 1 so einzutippen (oft der der Name des Befehls selbst)
• kursiv: Platzhalter für einen benutzerdefinierten Wert
• [-abc]: Ein oder alle Argumente innerhalb der Klammern sind Optional
• -a|-b: Optionen getrennt durch ein | dürfen nicht gleichzeitig verwendet werden.
• argument...: Argument ist wiederholbar
• [expression]...: Der gesamte Ausdruck ist wiederholbar
• (a | b): Gruppierung von Elementen (meine Ergänzung)

Die exakte Ausgabe kann je nach Ausgabegerät variieren. z.B. ist der von man verwendete Pager üblicherweise nicht in der Lage, kursiven Text im Terminal zu rendern, und stellt diesen unterstrichen oder in Farbe dar. Weitere Konvention ist, obligatorische Positionsparameter in Klammern, oder Benutzerdefinierte Werte, zusätzlich zum Unterstrich, in Grossbuchstaben zu setzen (`FILE`). **Wichtig**: im Rest der Manpage können auch unterstrichene Wörter vorkommen. Dies ist in manchen Fällen lediglich eine Hervorhebung, kann aber auch einen Link markieren dem mit gefolgt werden kann (mit neovim als Pager), Doppelklick mit der Maus funktioniert auch in den meisten Pagern.

# Beispiel SYNOPSIS
command (-a | -b) [-c ARGUMENT] [OPTION...] [--verbose | --quiet] FILE... [expression]

Konkret:

• command: so einzutippen (in der Manpage fett dargestellt)
• (-a | -b): -a oder -b muss vorhanden sein
• [-c ARGUMENT]: wahlweise Option -c mit Argument
• [OPTION...]: beliebige weitere Optionen, wobei in den meisten Programmen -xyz = -x -y -z (für Short Options ohne Argumente).
• [--verbose | --quiet]: --verbose oder --quiet kann vorhanden sein
• FILE...: Positionsparameter FILE ist ein benutzerdefinierter Wert der wiederholt werden kann. Hier der Pfad einer Datei.
• [expression]: optionaler Positionsparameter, hier ein Ausdruck.

Organisation

Die exakte Struktur ist nicht wirklich wichtig für die meisten Themen, da man in den meisten Fällen die geeignete Seite von selbst findet. Erst wenn sich ein Thema in mehreren Sektionen wiederfindet, muss sie spezifiziert werden. Beispiel: passwd ist ein Befehl sowie eine Konfigurationsdatei, weswegen eine Manpage in den Sektionen 1 und 5 gefunden werden kann. Gesucht wird in numerischer Reihenfolge, wobei die Sektionen 1 und 8 Vorrang haben (Befehle). Eine spezifische Sektion kann wie folgt angefragt werden:

man 5 passwd
# oder
man passwd.5

Generell bezeichnet der Ausdruck Programmers Manual die Sektionen 2-7. In den Manpage-Sektionen 2 und 3 enthält die SYNOPSIS die erforderlichen #include-Direktiven (Header) sowie die vollständige Funktionssignatur. Diese entspricht exakt der deklarativen C-Signatur der jeweiligen Schnittstelle. Dieser Punkt ist hauptsächlich für Entwickler interessant, denen wird das allerdings bereits bewusst sein.

Namen der Sektionen auf Englisch (aus dem Buch kopiert).

Mit apropos lässt sich nach Begriffen innerhalb des Abschnitts DESCRIPTION aller Manpages suchen. Der whatis Befehl listet alle vorhandenen Sektionen eines Befehls auf.

apropos printf # oder: man --apropos printf
whatis printf # oder: man --whatis printf

Die Installation (bzw. Deinstallation) von neuen Paketen fügt neue Datenbankeinträge in den Manpages hinzu, dies ist in den gängigen Distribution automatisiert. Falls das nicht der Fall ist, kann die Datenbank wie folgt aktualisiert werden:

sudo mandb
sudo makewhatis # Red Hat und FreeBSD

Interessantes und Tipps

• Es existieren alternative Pager. Neovim hat einen sehr guten eingebauten Pager. (Umgebungsvariable MANPAGER='nvim +Man!' setzen). Mit gO lässt sich ein Inhaltsverzeichnis öffnen.
• info Paket beinhaltet detailliertere, navigierbare Beschreibungen für Befehle mit Beispielen, eine Art Tutorial.
• tldr Paket für kurze Zusammenfassungen häufig genutzter Optionen eines Befehls.
• Nach exaktem Wort suchen (/ eingeben um Suche einzuleiten): \.
• Für Konfigurationsdateien existieren oft auch Manpages, man pacman.conf. Steht oft am Schluss vom Hauptdokument im SEE ALSO Abschnitt.
• Interessant, es existieren auch allgemeinere Manpages: man ascii, man units
• Mit einem Auto-Completion-Plugin für die Shell (z. B. zsh-completions für zsh) lassen sich auch Vorschläge für verfügbare Manpages anzeigen.
• Für die POSIX konforme Manpage, ein p an die Sektion anhängen: man 3p printf oderman printf.3p. Nützlich wenn ein portables Programm geschrieben wird. Manche Distros paketieren diese Manpages separat.
• Firefox mit @man Keyword sucht -> https://man.archlinux.org/search?q=%s&lang=en
• (pacman) Installierte Manpages eines Pakets anzeigen: pacman -Ql | grep man.
• (pacman) Herausfinden, welches Paket eine spezifische Manpage (hier aus der Sektion 2) besitzt bzw. installiert hat: pacman -Qo $(man -w 2 ).

Quellen:
`man man`
Evi Nemeth et al.: Unix and Linux System Administration Handbook