HOWTO zum Kommando "man" (Manual Pages)

(C) 2006-2013 T.Birnthaler/H.Gottschalk <howtos(at)ostc.de>
              OSTC Open Source Training and Consulting GmbH
              www.ostc.de


$Id: man-HOWTO.txt,v 1.9 2013/03/25 12:01:39 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   (Toc)

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   (Toc)

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..." <RETURN>) 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   (Toc)

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   (Toc)

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