HOWTO zum Kommando "man" (Manual Pages) (C) 2006-2013 T.Birnthaler/H.Gottschalk OSTC Open Source Training and Consulting GmbH http://www.ostc.de $Id: man-HOWTO.txt,v 1.10 2019/11/26 19:37:07 tsbirn Exp $ Dieses Dokument beschreibt den Einsatz des Kommando "man" zur Anzeige der UNIX-Dokumentation und das Erstellen eigener Man-Pages. ________________________________________________________________________________ INHALTSVERZEICHNIS 1) Struktur von Manpages 2) Aufruf von man 3) Eine eigene Manpage erstellen 4) Sonstiges ________________________________________________________________________________ 1) Struktur von Manpages ------------------------ Die Dokumentation eines UNIX-Systems ist in sogenannte "Manual-Seiten" (Manpages) eingeteilt und immer vollständig auf dem System verfügbar. Sie liegt meist in den Verzeichnissen /usr/man /usr/local/man /usr/share/man Die Manpages sind in folgende "Abschnitte" (sections) eingeteilt, die immer in Klammern nach dem Namen der Manpage angegeben werden (z.B. passwd(4)): +---+----------------------------------------------------------------------+ | N | Bedeutung | +---+----------------------------------------------------------------------+ | 1 | Ausführbare Programme oder Shellbefehle | | 2 | (C-)Systemaufrufe (Kernelfunktionen) | | 3 | (C-)Bibliotheksaufrufe (Funktionen in System-Bibliotheken /usr/lib) | | 4 | Gerätedateien (gewöhnlich in /dev) | | 5 | Formate + Bedeutung von Konfigurations/Logdateien (z.B. /etc/passwd) | | 6 | Spiele | | 7 | Makropakete und Konventionen (z.B. man(7), groff(7)) | | 8 | Systemadministrationsbefehle (in der Regel nur für root) | | 9 | Kernelroutinen [nicht Standard] | | l | Lokale Erweiterungen | +---+----------------------------------------------------------------------+ Jede Manpage ist nach einen festgelegten Aufbau in Elemente strukturiert, die durch ein GROSS geschriebenes Schlüsselwort eingeleitet werden (nicht alle Elemente müssen vorhanden sein). +--------------+---------------+-----------------------------------+ | Englisch | Deutsch | Bedeutung | +--------------+---------------+-----------------------------------+ | NAME | NAME | Name (einzeilige Beschreibung) | | SYNOPSIS | SYNTAX | Syntax-Zusammenfassung | | DESCRIPTION | BESCHREIBUNG | Beschreibung (vollständig) | | OPTIONS | OPTIONEN | Optionen | | OVERVIEW | ÜBERSICHT | Übersicht | | DEFAULTS | STANDARD | Normaleinstellungen | | ENVIRONMENT | UMGEBUNG | Umgebungsvariablen | | FILES | DATEIEN | (Konfigurations)Dateien | | EXAMPLES | BEISPIELE | Beispielaufrufe | | NOTES | BEMERKUNGEN | Bemerkungen | | SEE ALSO | SIEHE AUCH | Siehe auch (verwandte Manpages) | | REFERENCES | REFERENZEN | Verweise auf (verwandte Manpages) | | BUGS | FEHLER | Fehler | | AUTHOR | AUTOR | Autor(en) | | HISTORY | GESCHICHTE | Geschichte | +--------------+---------------+-----------------------------------+ 2) Aufruf von man ------------------ Mit dem Kommando "man" können diese Seiten zu den Kommandos, Konfigurations- dateien und vielen anderen Themen auf dem Bildschirm angezeigt werden. Dabei wird automatisch "more" zur seitenweisen Ausgabe verwendet (oder durch die Umgebungs-Variable "PAGER" wird ein anderes Tool zur seitenweisen Darstellung ausgewählt, z.B. "less"). PAGER=less; export PAGER # sh export PAGER=less # bash, ksh setenv PAGER = less # csh, tcsh Der Abschnitt "NAME" enthält eine einzeilige zusammenfassende Beschreibung. Mit "man -f" (bzw. "whatis") und "man -k" (bzw. "apropos") kann in diesen Einzeilern aller Manpages nach Namen bzw. Schlüsselworten gesucht werden. Das vollständige Durchlesen einer Manpage dauert oft zu lange, da sie doch sehr ausführlich und umfassend sind. Meist ist es geschickter, in einer Manpage per Textsuche (per "/TEXT..." ) nach den gesuchten Begriffen oder Optionen zu suchen. Ein Blick auf den Teil "REFERENCES/SEE ALSO/SIEHE AUCH" lohnt sich vor allem, um verwandte Kommandos zu finden. Allgemeiner man-Aufruf: man [-M PATH] # Suchpfad nach Manualseiten man [-s SECTION] CMD/FILE... # Manualseite zu CMD/FILE anzeigen (section, manual) man [SECTION] CMD/FILE... # Manualseite zu CMD/FILE anzeigen (manual) man -f FILE... # Dateiname in Manpage-Einzeiler suchen man -k KEYWORD... # Schlüsselwort in Manpage-Einzeiler suchen Achtung: Die Option "-s" (section) ist auf manchen Systemen wegzulassen. Beispiele für man-Aufrufe: man man # Manpage zu man(1) anzeigen man chmod # Manpage zu chmod(1) anzeigen man 1 passwd # Manpage zu passwd(1) anzeigen man 4 passwd # Manpage zu passwd(4) anzeigen man 7 signal # Manpage zu signal(7) anzeigen man -f passwd # Suche nach Kmdo "passwd" in einz. Beschr. (file) whatis passwd # Suche nach Kmdo "passwd" in einz. Beschr. man -k passwd # Suche nach Text "passwd" in einz. Beschr. (keyword) apropos passwd # Suche nach Text "passwd" in einz. Beschr. Die Manpages werden in ihrer Ausgangs-Form im "troff"-Format mit "gzip" komprimiert in folgenden Verzeichnissen abgelegt (eine Liste der Verzeichnisse erhält man mit "manpath"): /usr/local/man # Lokale (eigene) Manpages (veraltet) /usr/local/share/man # Lokale (eigene) Manpages (neu) /usr/share/man # System-Manpages /usr/share/man/man1/*.1.gz # System-Manpages aus Abschnitt 1 /usr/share/man/man1/man.1.gz # System-Manpages zu "man" aus Abschnitt 1 ... Wurde eine Manpage einmal angezeigt, dann ist eine mit "troff" vorübersetzte Form, die einfach per "cat" ausgegeben werden kann, in folgenden Verzeichnissen abgelegt (eine Liste der Verzeichnisse erhält man mit "manpath -c"): /var/cache/man/oldlocal # Lokale (eigene) Manpages (veraltet) /var/cache/man/oldlocal/index.db # Lokale (eigene) Manpages (veraltet, Datenbank) /var/cache/man/local # Lokale (eigene) Manpages (neu) /var/cache/man/local/index.db # Lokale (eigene) Manpages (neu, Datenbank) /var/cache/man/ # System-Manpages /var/cache/man/index.db # System-Manpages (Datenbank) /var/cache/man/cat1/* # System-Manpages aus Abschnitt 1 /var/cache/man/cat1/man # System-Manpages zu "man" aus Abschnitt 1 3) Eine eigene Manpage erstellen -------------------------------- Man-Pages werden im "troff"-Format erstellt (einem frühen Satzprogramm analog TeX oder LaTeX). Sie enthalten Steuerkommandos, die am Zeilenanfang stehen und durch einen "." eingeleitet werden: +-----+---------------------------------------+ | Kdo | Bedeutung | +-----+---------------------------------------+ | .\" | Kommentarzeile | | .TH | Titelzeile (topic header und footer) | | .SH | Abschnittüberschrift (section header) | | .fi | Blocksatz ein (format i) | | .nf | Blocksatz aus (no format) | +-----+---------------------------------------+ Im Text können spezielle Sequenzen zur Formatierung verwendet werden: +------+------------------------+ | Seq | Bedeutung | +------+------------------------+ | \fR | Normaler Text | | \fB | Fetter Text (bold) | | \fI | Kursiver Text (italic) | | \- | Gedankenstrich | +------+------------------------+ | \*:a | Umlaut "ä" | | \*:o | Umlaut "ö" | | \*:u | Umlaut "ü" | | \*:A | Umlaut "Ä" | | \*:O | Umlaut "Ö" | | \*:U | Umlaut "Ü" | | \*:ß | Umlaut "ß" | +------+------------------------+ Das Titelzeilen-Format besteht aus 5 Elementen: .TH NAME SEKTION DATUM AUTOR THEMA Beispiel für eine Titelzeile: .TH primzahl 1 "unten mitte" "unten links" "oben mitte" .TH primzahl 1 "Sep. 2005" T.Birnthaler "Linux-Kurs" Beispiel für eine Manpage: .\" Kommentar zur Manpage primzahl.1 .\".TH primzahl 1 "Sep. 2005" "T. Birnthaler" "Linux-Kurs" .TH primzahl 1 "unten mitte" "unten links" "oben mitte" .SH NAME primzahl \- Primzahlen von 1 bis 100 berechnen .SH SYNTAX primzahl .SH BESCHREIBUNG .fi Das Programm \fBprimzahl\fR berechnet alle Primzahlen zwischen 1 und 100. Es dient als Beispielprogramm für eine \fIManpage\fR. .nf .SH AUTOR Thomas Birnthaler (tb@ostc.de) Anzeige der obigen Manpage (-l=lokal): man -l primzahl.1 Abzulegen ist die erstellte Manpage "gzip"-komprimiert an folgender Stelle und anschließend mit Leserecht für alle auszustatten: /usr/local/share/man/man1/primzahl.1.gz chmod 444 /usr/local/share/man/man1/primzahl.1.gz Evtl. ist vorher das Verzeichnis "man1" anzulegen und mit den korrekten Zugriffsrechten zu versehen: mkdir /usr/local/share/man/man1 chmod 775 /usr/local/share/man/man1 4) Sonstiges ------------ Weitere Kommandos zur Anzeige von Hilfetexten: tkman KMDO # Grafische Anzeige aller Manpages xman KMDO # Grafische Anzeige aller Manpages info KMDO # GNU-Beschreibung zu KMDO help KMDO # Beschreibung zu eingebautem Shell-KMDO hilfe # SuSE-Hilfesystem aufrufen Im Konqueror können man/info-Seiten über spezielle URLs angezeigt werden: man: # Einstieg in alle Manpages im Konqueror man:KMDO # Manpage im Konqueror anzeigen info: # Einstieg in alle info-Pages im Konqueror info:KMDO # Manpage im Konqueror anzeigen