# 1.108.1

# Benutzung und Verwaltung lokaler Systemdokumentation

Beschreibung: Prüfungskandidaten sollten in der Lage sein, man und die Materialien in `/usr/share/doc/` zu benutzen und zu verwalten. Dieses Lernziel beinhaltet das Auffinden relevanter man Pages, das Durchsuchen von man Page-Abschnitten, das Auffinden von Kommandos und dazugehöriger man Pages und die Konfiguration des Zugangs zu man Sourcen und dem man System. Ebenfalls enthalten ist die Verwendung der Systemdokumentation in `/usr/share/doc/` und das Bestimmen, welche Dokumentation in `/usr/share/doc/` zu behalten ist.

Die wichtigsten Dateien, Bezeichnungen und Anwendungen:

- man
- apropos
- whatis
- `MANPATH`

Alleine das Lernen für die LPI101 Prüfung hat sicherlich jedem schon gezeigt, daß eine Online-Hilfe, die zudem für jedes einzelne Programm alle denkbaren Parameter aufführt und erklärt, von größter Wichtigkeit ist. Zu diesem Zweck stellt Linux (wie jedes andere Unix auch) ein Handbuchsystem zur Verfügung, das im Folgenden dargestellt werden soll.

Zu den reinen Handbuchseiten kommen noch weitere Dokumentationen hinzu, die entweder von den Autoren der jeweiligen Programme geschrieben wurden, oder von Gruppen, die sich zum Ziel gesetzt haben, Linux für viele Anwender durchschaubarer zu machen. Eine der wichtisten solchen Gruppen ist das Linux Documentation Project (LDP), das verschiedene Dokumentationen erstellt hat, die viele Fragen beantworten. Zu nennen sind hier im Wesentlichen die sogenannten HOWTOs (wie geht was) und die FAQs (frequently asked questions - häufig gestellte Fragen).

Diese Dokumentationen wurden bisher meist unterhalb des Verzeichnisses `/usr/doc` gespeichert, seit der neuen Version 2.0 des Filesystem Hierachy Standard wurde daraus `/usr/share/doc`.

### Das Handbuchsystem von Linux

Linux bietet ein Handbuchsystem an, das offen für zusätzliche Seiten ist. Im Prinzip sollte jedes zu installierende Programm seine Handbuchseite gleich mitbringen. Der Begriff Handbuchseite mag etwas verwirren, eine Handbuchseite besteht gewöhnlich aus vielen einzelnen Seiten, die des Befehls mount(8) hat auf meinem System z.B. 18 physikalische Seiten.

Die Handbuchseiten sind in logische Sektionen aufgeteilt, deren Bezeichnung bei der Referenz eines Befehl dem Befehl in runden Klammern nachgestellt wird. So bedeutet das obige Beispiel mount(8) eben, daß die Handbuchseite für den Befehl mount aus Sektion 8 gemeint ist.

Folgende Handbuchsektionen werden traditionell unterstützt:

1 - Kommandos (User Commands)
  Die Kommandos, die vom Benutzer aus einer Shell heraus ausgeführt werden können.
2 - Systemaufrufe (System Calls)
  Funktionen, die vom Kernel selbst für den Aufrufenden ausgeführt werden.
3 - C-Bibliotheksfunktionen (Subroutines)
  Der Großteil der Funktionen der Library libc, so wie sort(3))
4 - Gerätedateien (Devices)
  Dateien, die in /dev zu finden sind.
5 - Dateiformate und Konventionen (File Formats)
  Formate von menschenlesbaren Dateien wie /etc/passwd, /etc/inittab, usw.
6 - Spiele (Games)
  Spiele und Unterhaltung
7 - Makropakete und Konventionen
  Eine Beschreibung des standardmäßigen Layouts des Dateisystems, Formatbeschreibungen für GROFF Makropakete und ähnliche Dinge.
8 - Kommandos für die Systemverwaltung (Sys. Administration)
  Kommandos wie mount(8), die nur durch den Superuser ausführbar sind.
9 - Kernelroutinen (Kernel)
  Dies ist kein standardisiertes Kapitel und wird geführt, da der Quellcode des Linux Kernels frei verfügbar ist und viele Leute an Änderungen des Kernels parallel arbeiten.

Jede einzelne Handbuchseite ist in einer Datei abgelegt, die aber nicht etwa die formatierte ASCII Ausgabe der Handbuchseite enthält, sondern einen Quelltext für das groff-Textformatiersystem. Damit ist gewährleistet, daß die verschiedenen Handbuchprogramme, die diese Seiten darstellen wollen, das jeweils führ ihre Darstellungsform optimale Ausgabeformat erhalten. So können die Seiten auf graphischen Systemen korrekt dargestellt werden, mit verschiedenen Schriften oder Darstellungsattributen, während sie auf textbasierten Systemen einfacher, aber eben auch korrekt formatiert dargestellt werden.

Die Dateien, die diese Handbuchseiten im Quelltext beinhalten liegen sektionsweise in Verzeichnissen, die jeweils den Namen der Sektion tragen (wie etwa man1, man2, man3, ...). In der Regel werden die Dateien in diesen Verzeichnissen komprimiert abgelegt um Festplattenplatz zu sparen. Daher tragen sie normalerweise die Endung .gz

Um Handbuchseiten schneller darstellen zu können, besteht die Möglichkeit, die Formatierung von GROFF nach ASCII schon vorher vorzunehmen. Dann werden die Handbuchseiten im sogenannten CAT-Format (weil sie mit cat anzeigbar sind) gespeichert. Der Nachteil dieser Technik ist der erhöhte Bedarf an Speicherplatz auf den Platten, der Vorteil die schnellere Darstellung der Seiten mit dem man-Kommando. In diesem Fall werden die vorformatierten Seiten in Unterverzeichnissen gespeichert, die statt man jetzt cat heißen, also cat1, cat2, cat3, ...

Damit das Handbuchsystem nicht immer alle denkbaren Verzeichnisse mit Handbuchseiten durchsuchen muß, bevor eine Seite angezeigt werden kann, existiert eine Indexdatenbank, die die Namen der Handbuchseiten, ihre Kurzbeschreibung und den Platz, wo die eigentliche Seite zu finden ist. Das Programm mandb zur Verwaltung dieser Datenbank wird weiter unten noch genauer beschrieben.

### Programme zum Umgang mit den Handbuchseiten

Es existieren verschiedene Programme, um sich Handbuchseiten anzeigen zu lassen. Die Palette dieser Programme reicht vom Standard-Handbuchprogramm man über Filterprogramme wie rman bis zu graphischen Programmen wie xman oder tkman.

Das wichtigste dieser Programme ist das Programm man. Es ist ein sehr komplexes Dienstprogramm, das hier nur kurz dargestellt werden soll, Details sind der Handbuchseite zu entnehmen...

man zeigt Handbuchseiten in einem Textformat an, das auf jeder Konsole darstellbar ist. Es hat sehr viele Parameter, von denen hier nur die wichtigsten erklärt werden, die für die LPI-101 Prüfung notwendig sind.

Die Aufrufform von man ist:

      man [Optionen] [Sektion] Name

Im einfachsten Fall wird also nur der Name der gesuchten Seite angegeben, genauer gesagt der Name des Programms, dessen Handbuchseite Sie lesen wollen. Um also Informationen über den Befehl `fdisk` zu bekommen, wird einfach der Befehl

      man fdisk

eingegeben. Dieser Befehl sucht jetzt nach dem ersten Vorkommen einer Handbuchseite mit Namen `fdisk` und stellt sie mittels less dar. Dabei ist es unerheblich, in welcher Sektion des Handbuchsystems diese Seite liegt. Da aber die Sektionen der Reihe nach durchsucht werden, wird immer die Handbuchseite der 1. Sektion dargestellt, wenn sie existiert.

Das kann zu Problemen führen, wenn es mehrere Handbuchseiten gleichen Namens gibt. In diesem Fall kann der Parameter `-a` angegeben werden. Jetzt zeigt man alle gefundenen Handbuchseiten dieses Namens hintereinander an.

Um ganz gezielt nach einer Handbuchseite in einer bestimmten Sektion zu suchen, kann aber auch die gewünschte Sektion mit angegeben werden. Ein Beispiel:

Linux kennt sowohl ein Programm mit Namen `passwd` (zum Ändern von Passwörtern), als auch eine Datei `/etc/passwd` (in der die Userinformationen gespeichert sind). Die Handbuchseite für das Programm `passwd` liegt in der Sektion 1 (User Kommandos), die Beschreibung der Datei `passwd` finden wir in der Sektion 5 (Dateiformate).

Wenn wir jetzt die Handbuchseite für `passwd` aufrufen, indem wir schreiben

      man passwd

so bekommen wir zwangsläufig die Seite über das Programm und nicht über die Datei. Wie oben schon erwähnt, werden die Sektionen ja der Reihe nach (1-9) durchsucht und die erste gefundene Seite wird angezeigt. Um also direkt die Handbuchseite der Datei `passwd` anzuzeigen müssen wir die gewünschte Sektion (hier 5) mit angeben. Wir schreiben also

      man 5 passwd

und bekommen so die Handbuchseite, die uns das Format der Datei `/etc/passwd` anzeigt.

Es existieren noch zwei weitere kleine Dienstprogramme, die mit den Handbuchseiten arbeiten, whatis und apropos. Beide bedienen sich ursprünglich einer kleinen Textdatenbank, die jeweils nur den Namen einer Handbuchseite und die Kurzbeschreibung des Befehls enthält. Die sogenannte `whatis-Datenbank`. Nachdem heute das Linux-Handbuchseitensystem sowieso eine Indexdatenbank aufrechterhält, die auch die Namen und Kurzbeschreibungen speichert, arbeiten whatis und apropos heute mit dieser Indexdatenbank. Nur wenn diese Indexdatenbank nicht gefunden wird, wird die alte whatis-Datenbank durchsucht.

Die Kurzbeschreibungen haben immer das Format:

      Name (Handbuchsektion) - Beschreibung

Das Programm whatis wird zusammen mit einem Suchbegriff eingegeben. Es durchsucht jetzt die Kurzbeschreibungen, allerdings nur die linke Spalte dieser Beschreibungen, also die Spalte mit dem Namen. Als Ausgabe werden alle Zeilen dargestellt, die den Suchbegriff in dieser linken Spalte der Kurzbeschreibung haben. Der Programmaufruf

      whatis passwd

könnte also (wenn auch die deutschen Handbuchseiten installiert sind) die folgende Ausgabe haben:

    passwd (1)           - ändert das Paßwort zum System
    passwd (5)           - Paßwort-Datei
    passwd (5)           - The password file
    passwd (1)           - change user password

Wie der Name schon andeutet, zeigt whatis also einfach, was ein Programm oder eine Datei ist. Das hilft uns natürlich nur weiter, wenn wir den Namen des Programms schon kennen. Wenn wir aber nicht mehr wissen, mit welchem Programm ein Passwort geändert wird, dann kann uns das Programm apropos weiterhelfen. Wie bei whatis, so geben wir auch dem Programm apropos einen Suchbegriff mit. Wie whatis durchsucht apropos auch wieder die Indexdatenbank bzw. die whatis-Datenbank. Nur durchsucht apropos nicht nur die linke spalte, sondern die ganze Zeile dieser Kurzbeschreibung. Wir suchen also nach dem Begriff Paßwort und schreiben

      apropos paßwort

und bekommen als Ausgabe alle Zeilen der Indexdatenbank, die diesen Suchbegiff enthalten:

    getpwuid (3)         - arbeite mit Paßworteintrag
    passwd (1)           - ändert das Paßwort zum System
    fgetpwent (3)        - arbeite mit Paßworteintrag
    endpwent (3)         - arbeite mit Paßworteintrag
    chsh (1)             - ändert den Loginshell Eintrag in der Paßwortdatei
    getpwnam (3)         - arbeite mit Paßworteintrag
    setpwent (3)         - arbeite mit Paßworteintrag
    passwd (5)           - Paßwort-Datei
    getpwent (3)         - arbeite mit Paßworteintrag
    getpw (3)            - Re-konstruiere eine Paßwortdateieintrag

Jetzt können wir uns aus dieser Liste das Programm aussuchen, das unseren Ansprüchen gerecht wird...

### Die Verwaltungsarbeiten für die Handbuchseiten

Physikalisch liegen die Handbuchseiten in verschiedenen Teilen der Dateisystem-Hierarchie. So kann jede wichtige Unterhierarchie des Dateisystems ein eigenes Handbuchverzeichnis besitzen, das in der Regel dann den Namen man trägt. Typische Orte für Handbuchseiten waren früher also:

      /usr/man
      /usr/local/man
      /usr/X11R6/man
      /usr/openwin/man
      /usr/share/man

Nach der Version 2 des Linux Dateisystemstandards sollten Handbuchseiten heute grundsätzlich unter `/usr/share/man` liegen. Auch dort können aber wiederum mehrere Verzeichnisse mit Handbuchseiten abgelegt sein, beispielsweise für unterschiedliche Sprachen. Also etwa

      /usr/share/man
      /usr/share/man/de
      ...

Jedes dieser Verzeichnisse enthält wiederum Unterverzeichnisse für jede Sektion des Handbuchs. Enthalten diese Verzeichnisse GROFF-Quelltext (unformatierte Handbuchseiten), so tragen sie die Namen `man1, man2, man3, ...`, enthalten sie aber bereits vorformatierten ASCII-Text, so werden sie `cat1, cat2, cat3, ...` genannt.

Weil die Handbuchseiten praktisch alle im /usr/share-Dateisystem oder darunter zu finden sind, und dieses Dateisystem ja oftmals ReadOnly gemountet ist, wird meist im /var-Verzeichnis noch eine Handbuchhierarchie gehalten, die für die Speicherung der Index-Datenbank, der whatis-Datenbank und der cat-manpages dient. Diese Hierarchie liegt oft unter /var/cache/man oder /var/catman

Damit die Indexdatenbank aktualisiert werden kann (wenn z.B. neue Programmpakete installiert wurden), existiert das Programm mandb. Dieses Programm aktualisiert oder erstellt die Indexdatenbank für alle Handbuchseiten.

Damit dieses Programm tatsächlich alle Verzeichnisse findet, die Handbuchseiten enthalten, bzw. damit auch das man-Kommando die Reihenfolge der Durchsuchung weiß, werden alle Verzeichnisse, die Handbuchseiten enthalten, in einer Variable mit Namen `MANPATH` gespeichert. Sie ist aufgabaut wie der Suchpfad, also werden die Namen der Verzeichnisse mit Doppelpunkt voneinander getrennt.

Ein Aufruf von

      echo $MANPATH

zeigt also den Suchpfad für die Handbuchseiten und hauptsächlich dadurch auch die Reihenfolge, in der diese Verzeichnisse durchsucht werden. Das ist wichtig, da ja das man-Kommando beispielsweise nur die erste gefundene Handbuchseite zeigt, wenn nicht die Option `-a` mitgegeben wurde.

Diese Handbuchpfadvariable wird entweder in einer Startdatei wie `/etc/profile` angelegt, oder - seltener - durch ein Programm namens manpath gesetzt. Dieses Programm wird auch dann automatisch von man aufgerufen, wenn die Variable MANPATH nicht existiert. Das kann in einem System ohne mehrsprachige Handbuchseiten ganz praktisch sein, sobald aber mehrere Sprachen benutzt werden zeigt es Schwächen.

Da das Programm manpath sich den Handbuchpfad einfach dadurch erstellt, daß es alle Verzeichnisse durchscannt und Unterverzeichnisse namens MAN oder man sucht, kann die Reihenfolge der gefundenen Verzeichnisse nicht manipuliert werden. Sind aber z.B. deutsche und englische Handbuchseiten installiert, so wird man es wahrscheinlich vorziehen, dem Pfad der deutschen Seiten vor dem der englischen anzugeben. Das führt dann dazu, daß - wenn eine deutsche Handbuchseite zu einem Programm existiert - die deutsche Seite aufgerufen wird, ansonsten die englische. In diesem Fall bleibt es notwendig, die MANPATH-Variable zu setzen, um diese Reihenfolge festzulegen.

Wenn es gewünscht wird, daß alle (oder bestimmte) Handbuchseiten als ASCII Dateien vorformatiert werden sollen, dann kann diese Aufgabe durch das Programm catman erledigt werden. Dieses Programm legt - meist im /var-Verzeichnis - die entsprechenden cat-Verzeichnisse an und speichert die Handbuchseiten in reinem Textformat lesbar dort hinein. Da heute Festplattenplatz kein großes Kriterium ist, kann man davon durchaus Gebrauch machen, es ersetzt aber nicht die GROFF-Dateien. Denn für alle anderen Handbuchprogramme wie xman, tkman oder rman benötigen wir diese GROFF-Quellen.

### Info und seine Seiten

Die Free Software Foundation hat ein weiteres Prinzip ins Leben gerufen, um Informationen über Programmpakete dem User bereitzustellen, das info-System. Dieses System ist gedacht, um größere Informationsmengen als die Handbuchseiten zu transportieren und funktioniert ein bischen ähnlich wie HTML. Es gibt Hypertext-Verweise auf andere Seiten und ein Thema hat oftmals mehrere Dateien, die Informationen darüber bereitstellen. Das Programm, mit dem diese Info-Dokumentationen dargestellt werden können heißt info

Dieses Programm ist etwas spartanisch in der Benutzung, trotzdem kann es in vielen Fällen Informationen vermitteln, die wesentlich weitergehen, als die der Handbuchseiten. Nebenbei kann info heute auch Handbuchseiten darstellen, falls also im Verzeichnis der Info-Dateien (meist /usr/info, /usr/share/info) keine Informationen zu finden sind, durchsucht info auch noch den MANPATH und zeigt Handbuchseiten an.

Wird info ohne Parameter aufgerufen, so startet es in einem globalen Menü, sozusagen dem Hauptmenü, in dem dann alle vorhandenen Nodes angezeigt sind. Eine solche Node wird angewählt, indem der Cursor auf den entsprechenden Text plaziert wird und dann die Enter-Taste gedrückt wird.

Wird info mit einem Parameter aufgerufen, so zeigt es gleich die Informationen über diesen Parameter, sozusagen die Hauptseite zum angegebenen Thema. Ein Aufruf von

      info emacs

bringt uns also auf die Hauptseite der Info-Dateien über Emacs. Dort finden wir wiederum Nodes, auf die wir weiterspringen können. Diese Unternodes sind aber auch direkt anwählbar z.B. mit

      info emacs buffers

kommen wir sofort auf die Node Buffers der Datei Emacs des Info-Systems.

Um genauere Informationen über info zu erhalten bietet das info-System eine Art Selbsthilfe, die durch den Aufruf

      info info

gestartet wird. Dort werden dann Schritt für Schritt der Umgang mit info erklärt.

### HOWTOs und FAQs

Neben den bisher geschilderten Informationsquellen gibt es natürlich noch weitere Formen, deren Existenz bekannt sein muß. Im Wesentlichen handelt es sich dabei um die sogenannten HOWTOs und FAQs. Im Gegensatz zu den bisher besprochenen Dokumentationen enthalten diese Quellen nicht Online-Hilfen, die als schnelle Nachschlagmöglichkeiten gedacht sind, sondern die HOWTOs bieten fundierte Anleitungen, wie bestimmte Probleme zu lösen sind, wie bestimmte Dienste zu konfigurieren sind oder ähnliches. Die FAQs (Frequently Asked Questions - Häufig gestellte Fragen) dagegen zeigen häufig gestellte Fragen zu bestimmten Themen und natürlich deren Antworten.

Typischerweise finden sich diese Dokumente im Verzeichnis `/usr/doc` oder `/usr/share/doc`. Sie sind aber nicht grundsätzlich installiert, die neuesten Versionen finden sich im Internet. Um zu vermeiden, daß es zu einem unübersichtlichen Chaos bei dieser Form der Dokumentation kommt, werden die HOWTOs und FAQs zentral vom Linux Documentation Project (LDP) verwaltet. Das LDP stellt all seine Dokumentationen unter der Adresse http://www.linuxdoc.org zur Verfügung.

Welche dieser Dokumentationen auf dem System installiert sein sollen, hängt von mehreren Faktoren ab. Neben der Frage des Plattenplatzes stellt sich die der Brauchbarkeit. Wenn ein System keinerlei ISDN-Anbindung hat muß wohl kaum ein ISDN-HOWTO installiert werden. Andererseits schaden diese Dokumente nicht, wenn genug Platz zur Verfügung steht. Die meisten dieser Dokumente stehen inzwischen in einem HTML-Format zur Verfügung, so daß man auch einen zentralen Dokumentationsserver im lokalen Netz aufbauen kann, von dem aus alle Dokumente gelesen werden können.

### Andere Dokumentationen

Neben den zentral verwalteten Dokumentationen der HOWTOs und FAQs bringt jedes größere (manchmal auch kleinere) Paket noch Dokumentationen mit. Es hat sich inzwischen durchgesetzt, daß solche Dokumentationen unter `/usr/share/doc/packages/Paketname` oder `/usr/share/doc/Paketname` abgelegt werden. Hier sollten sich zumindest eine Datei mit Namen README befinden, die eine erste Beschreibung des Paketes beinhaltet. Oft sind in diesen Verzeichnissen aber ganze Dokumentationen zu finden, die jeden Schritt, von der Installation über die Benutzung bis zur Administration beschreiben.