"Fossies" - the Fresh Open Source Software archive

Member "manpages-de-0.11/generated/man7/man-pages.7" of archive manpages-de_0.11.orig.tar.gz:

MAN\-PAGES

BEZEICHNUNG

ÜBERSICHT

BESCHREIBUNG

Gliederung der Handbuchseiten

Die Handbuchseiten sind traditionell in die folgenden Abschnitte eingeteilt:

1 Befehle (Programme)

Diese Befehle kann ein Benutzer in der Shell ausführen.

2 Systemaufrufe

Diese Funktionen müssen vom Kernel ausgeführt werden.

3 Bibliotheksaufrufe

die Mehrzahl der Libc-Funktionen

4 Spezialdateien (Geräte)

die Dateien in /dev

5 Dateiformate und Konventionen

die Formate von /etc/passwd und weiteren menschenlesbaren Dateien

6 Spiele

7 Konventionen und Verschiedenes

Überblick über verschiedene Themen, Konventionen und Protokolle, Zeichensatz-Standards und diverse andere Dinge

8 Befehle für die Systemverwaltung

Dazu gehören Befehle wie mount(8). Viele davon kann nur root ausführen.

Makropaket

Konventionen für die Gestaltung der Quelltexte

Neue Sätze sollten auf einer neuen Zeile beginnen. Dadurch können die Auswirkungen von Patches besser verfolgt werden, da Patches oft nur einzelne Sätze verändern.  

Titelzeile

.TH Titel Abschnitt Datum Quelle Handbuch.

Titel

der Titel der Handbuchseite in Großbuchstaben (z. B. MAN-PAGES)

Abschnitt

die Nummer des Abschnitts, in dem die Handbuchseite eingeordnet wurde (z. B. 7)

Datum

Das Datum der letzten Überarbeitung – denken Sie daran, es bei jeder Änderung der Handbuchseite zu aktualisieren, weil dies die allgemeinste Form einer Versionskontrolle ist. Es sollte in der Form JJJJ-MM-TT geschrieben werden.

Quelle

die Quelle von Befehl, Funktion oder Systemaufruf

Für die wenigen Handbuchseiten in den Abschnitten 1 und 8 werden Sie vielleicht nur GNU schreiben wollen.

Für Systemaufrufe schreiben Sie einfach Linux. (Eine frühere Praxis war es, die Kernel-Version anzugeben, für die die Seite geschrieben oder mit der sie überprüft wurde. Dies wurde jedoch nie konsequent durchgeführt und war vielleicht schlimmer als gar keine Versionsnummer. Vermeiden Sie künftig die Versionsnummer .)

Für Bibliotheksaufrufe, die Teil der Glibc oder einer der anderen gängigen GNU-Bibliotheken sind, schreiben Sie einfach GNU C Library, GNU oder eine leere Zeichenkette.

Verwenden Sie für Seiten aus Abschnitt 4 Linux.

Wählen Sie in Zweifelsfällen einfach Linux oder GNU.

Handbuch

der Titel des Handbuchs (z. B. für Seiten der Abschnitte 2 und 3 aus dem Paket man-pages verwenden Sie bitte Linux-Programmierhandbuch.

Abschnitte innerhalb einer Handbuchseite

BEZEICHNUNG
ÜBERSICHT
KONFIGURATION       [im Allgemeinen nur in Abschnitt 4]
BESCHREIBUNG
OPTIONEN            [im Allgemeinen nur in den Abschnitten 1, 8]
EXIT-STATUS         [im Allgemeinen nur in den Abschnitten 1 und 8]
RÜCKGABEWERT        [im Allgemeinen nur in den Abschnitten 2 und 3]
FEHLER              [typischerweise nur in den Abschnitten 2 und 3]
UMGEBUNGSVARIABLE
DATEIEN
VERSIONEN           [im Allgemeinen nur in den Abschnitten 2 und 3]
KONFORM ZU
ANMERKUNGEN
FEHLER
BEISPIEL
SIEHE AUCH

Die folgende Liste geht näher auf den Inhalt jedes der oben genannten Abschnitte ein.

NAME

Name der Handbuchseite; siehe man(7) für wichtige Einzelheiten über die Zeile(n), die dem Befehl .SH NAME folgen sollte(n)

ÜBERSICHT

beschreibt kurz den Befehl oder die Schnittstelle der Funktion. Für Befehle beschreibt dieser Abschnitt die Syntax des Befehls und seine Argumente (einschließlich Optionen); Fettschrift bedeutet, das der Text genau so eingegeben werden muss, austauschbare Argumente werden durch Kursivschrift gekennzeichnet. Klammern ([]) umgeben optionale Argumente, senkrechte Striche (|) trennen Elemente, von denen eins auszuwählen ist und Ellipsen (...) können wiederholt werden. Für Funktionen enthält er die Deklarationen aller erforderlichen Daten oder #include-Anweisungen, gefolgt von der Funktionsdeklaration.

Wenn ein Feature-Test-Makro definiert werden muss, um die Deklaration einer Funktion (oder einer Variable) aus einer Header-Datei zu erhalten, dann sollte das in der ÜBERSICHT angegeben werden. Wie es gemacht wird, ist in feature_test_macros(7) beschrieben.

KONFIGURATION

Konfigurationsdetails für ein Gerät; Dieser Abschnitt erscheint in der Regel nur in Seiten aus Abschnitt 4.

BESCHREIBUNG

erklärt, was das Programm, die Funktion oder das Format bezwecken. Besprechen Sie die Interaktion mit Dateien und Standardeingabe und was in der Standardausgabe oder der Standardfehlerausgabe ausgegeben wird. Lassen Sie Interna und Details der Implementierung aus, wenn sie nicht entscheidend für das Verständnis der Schnittstelle sind. Beschreiben Sie den üblichen Fall, für Informationen über Befehlszeilenoptionen eines Programms verwenden Sie den Abschnitt OPTIONS.

OPTIONEN

beschreibt die von einem Programm akzeptierten Befehlszeilenoptionen und wie sie das Verhalten des Programms verändern. Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein.

EXIT-STATUS

Hier werden die möglichen Werte für den Exit-Status eines Programms und die Umstände, die zur Rückgabe dieser Werte führen, angegeben. Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein..

RÜCKGABEWERT

Dieser Abschnitt enthält für Handbuchseiten aus den Abschnitten 2 und 3 die Rückgabewerte der Bibliotheksfunktion für die aufrufende Routine und erläutert die Bedingungen, die zu einem bestimmten Rückgabewert führen.

FEHLER

Dieser Abschnitt enthält für Handbuchseiten aus den Abschnitten 2 und 3 mögliche Werte, die im Fehlerfall in errno platziert werden und erläutert mögliche Ursachen der Fehler. Die Fehlerliste sollte alphabetisch sortiert sein.

UMGEBUNGSVARIABLEN

gibt alle Umgebungsvariablen an, die auf das Programm einwirken und erläutert, was sie bewirken.

DATEIEN

führt die Dateien auf, die von dem Programm oder der Funktion benutzt werden: beispielsweise Konfigurationsdateien, Initialisierungsskripte und Dateien, die bearbeitet werden. Geben Sie den vollständigen Pfadnamen dieser Dateien an und nutzen Sie den Installationsprozess, um das Verzeichnis den Erfordernissen der Benutzer anzupassen. Für viele Programme ist als Installationsverzeichnis /usr/local voreingestellt. Ihre grundlegende Handbuchseite sollte daher /usr/local als Basis verwenden.

VERSIONEN

Hier steht eine kurze Zusammenfassung der Linux-Kernel oder Glibc-Versionen, in denen ein Systemaufruf oder eine Bibliotheksfunktion erschien oder das Verhalten wesentlich veränderte. Als allgemeine Regel gilt, dass jede neue Schnittstelle einen VERSIONEN-Abschnitt in der Handbuchseite bewirkt. Leider verfügen viele bestehende Handbuchseiten nicht über diese Informationen (da es dafür keine entsprechende Richtlinie gab, als sie geschrieben wurden). Patches zur Ergänzung dieser Abschnitte sind willkommen. Aus der Sicht von Programmierern, die neuen Code schreiben, werden diese Informationen wohl nur interessant sein für Kernel-Schnittstellen, die in Linux 2.4 oder später hinzugefügt wurden und für geänderte Bibliotheksfunktionen in der Glibc seit Version 2.1. (D. h. also Veränderungen seit Kernel 2.2 und Glibc 2.0).

Auch die Handbuchseite über Systemaufrufe (syscalls(2)) enthält Informationen über die Kernel-Versionen, in denen bestimmte Systemaufrufe erstmals vorkamen.

KONFORM ZU

Dieser Abschnitt beschreibt alle Normen oder Konventionen, die die Funktion oder einen von der Handbuchseite beschrieben Befehl betreffen. Für eine Handbuchseite in Abschnitt 2 oder 3, sollten hier die POSIX.1-Version(en) stehen, denen der Aufruf entspricht. Auch sollte angegeben werden, ob der Aufruf in C99 beschrieben ist. (Sorgen Sie sich nicht zu sehr über andere Standards wie SUS, SUSv2 und XPG oder die SVr4- und 4.xBSD-Implementierungsstandards, es sei denn, der Aufruf wurde in diesen Standards beschrieben, ist aber nicht in der aktuellen Version von POSIX.1 enthalten; siehe standards(7).)

Wenn der Aufruf von keinen Standards geregelt ist, aber allgemein auf anderen Systemen vorhanden ist, erwähnen Sie das. Wenn der Aufruf Linux-spezifisch ist, erwähnen Sie auch das.

Wenn dieser Abschnitt nur aus einer Liste von Standards besteht (das ist üblicherweise der Fall), beenden Sie die Liste mit einem Punkt (aq.aq).

ANMERKUNGEN

enthält verschiedene Anmerkungen. Für Handbuchseiten der Abschnitte 2 und 3 werden Sie vielleicht die Unterabschnitte (SS) Anmerkungen zu Linux und Anmerkungen zur Glibc nützlich finden.

FEHLER

führt Einschränkungen, bekannte Mängel oder Unannehmlichkeiten und weiteres fragwürdiges Verhalten auf.

BEISPIEL

Dieser Abschnitt enthält ein oder mehrere Beispiele für die Anwendung der Funktion, der Datei oder des Befehls. Wie Beispielprogramme geschrieben werden sollten, beschreibt der Abschnitt Beispielprogramme weiter unten.

AUTOREN

gibt die Autoren der Dokumentation oder des Programms an. Von einem AUTOREN-Bereich wird entschieden abgeraten. Allgemein ist es besser, nicht jede Seite mit einer Liste von (im Laufe der Zeit potenziell zahlreichen) Autoren vollzustopfen. Wenn Sie eine Seite schreiben oder signifikant verändern, fügen Sie einen Copyright-Vermerk als Kommentar in der Quelldatei ein. Wenn Sie der Autor eines Gerätetreibers sind und eine Adresse für das Melden von Fehlern angeben wollen, tun Sie das im Abschnitt FEHLER.

SIEHE AUCH

enthält eine durch Kommas gegliederte Liste verwandter Handbuchseiten. Die Liste ist nach Abschnittsnummern und in den Abschnitten alphabetisch sortiert. Manchmal folgen weitere Handbuchseiten oder Dokumente mit inhaltlichem Bezug. Schließen Sie die Liste nicht mit einem Punkt ab.

Verwendung von Schriftarten

Funktionsargumente werden immer kursiv geschrieben, auch in der ÜBERSICHT. Der Rest der Funktion wird fett geschrieben:

int meineFunktion(int argc, char **argv);

Variablennamen sollten wie die Namen von Argumenten kursiv geschrieben werden.

Dateinamen (ob Pfadnamen oder Verweise auf Dateien im Verzeichnis /usr/include) sind immer kursiv (z. B. <stdio.h>), außer in der ÜBERSICHT, wo eingefügte Dateien fett geschrieben werden (z. B. #include <stdio.h>). Wenn Sie auf eine Standard-Include-Datei unter /usr/include verweisen, umgeben Sie die Header-Datei wie in C gebräuchlich mit spitzen Klammern (z.B. <stdio.h>).

Spezielle Makros, die in der Regel mit Großbuchstaben geschrieben werden, werden in Fettdruck gesetzt (z.B. MAXINT). Ausnahme: Schreiben Sie NULL nicht fett.

Bei der Aufzählung einer Liste von Fehlercodes werden die Codes in Fettschrift geschrieben. (Diese Liste verwendet in der Regel das Makro .TP.)

Vollständige Befehle sollten, wenn sie lang sind, eine eigene, eingerückte Zeile bekommen; zum Beispiel:

man 7 man-pages

Ausdrücke, wenn Sie nicht auf einer separaten Zeile eingerückt geschrieben werden, sollten kursiv gesetzt werden. Auch hier kann die Verwendung von geschützten Leerzeichen angezeigt sein, wenn der Ausdruck in den normalen Text integriert ist.

Jeder Hinweis auf den Gegenstand der aktuellen Handbuchseite sollte mit diesem Namen in Fettschrift geschrieben werden. Wenn das Thema eine Funktion ist (d.h., die Handbuchseite gehört zu den Abschnitten 2 oder 3), dann sollte der Name ein Paar von Klammern in Normalschrift (Roman) folgen. Zum Beispiel würden in der Handbuchseite von fcntl(2) Verweise auf das Thema der Seite als fcntl() geschrieben werden. Die empfohlene Schreibweise in der Quelldatei ist

    .BR fcntl ().

Jede Bezugnahme auf eine andere Handbuchseite sollte den Namen fett schreiben und immer ohne Leerräume von der Nummer des Abschnitts in Normalschrift (Roman) gefolgt werden; (z. B. intro(2)). Die empfohlene Schreibweise in der Quelldatei ist

    .BR intro (2).

Rechtschreibung

Beispielprogramme und Shell-Sitzungen

*

Beispielprogramme sollten in C geschrieben sein.

*

Ein Beispielprogramm ist nur dann notwendig und sinnvoll, wenn es inhaltlich weiter geht als das, was leicht in einer textuellen Beschreibung der Schnittstelle bereitgestellt werden kann. Ein Beispielprogramm, das nichts Anderes tut, als eine Schnittstelle aufzurufen, hat in der Regel wenig Sinn.

*

Beispielprogramme sollten eher kurz sein (vorzugsweise weniger als 100 Zeilen, idealerweise weniger als 50 Zeilen).

*

Beispielprogramme sollten nach dem Aufruf von System- und Bibliotheksfunktionen prüfen, ob Fehler aufgetreten sind.

*

Beispielprogramme sollten vollständig sein und keine Warnungen ausgeben, wenn sie mit cc -Wall kompiliert werden.

*

Soweit möglich und angebracht, sollten Beispielprogramme Experimente ermöglichen, wie sich ihr Verhalten durch Variation der Eingabe verändert (idealerweise mittels Befehlszeilenargumenten oder alternativ durch vom Programm gelesene Eingaben).

*

Beispielprogramme sollten im Stil von Kernighan und Ritchie (mit Einzügen von 4 Leerzeichen) verfasst werden. (Verwenden Sie in Quelltexten keine Tabulatoren!)

In wait(2) und pipe(2) finden Sie vorbildliche Beispielprogramme.

Wenn Sie eine Shell-Sitzung einfügen, welche die Verwendung eines Programms oder andere Möglichkeiten des Systems demonstriert, wählen Sie Fettschrift für vom Benutzer eingegebenen Text, um ihn von der vom System erzeugten Ausgabe zu unterscheiden.  

Einzug bei Struktur-Definitionen, Protokollen von Shell-Sitzungen usw.

BEISPIEL

SIEHE AUCH

KOLOPHON

ÜBERSETZUNG

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an <debian-l10n-german@lists.debian.org>.

Index

BEZEICHNUNG

ÜBERSICHT

BESCHREIBUNG

Gliederung der Handbuchseiten

Makropaket

Konventionen für die Gestaltung der Quelltexte

Titelzeile

Abschnitte innerhalb einer Handbuchseite

Verwendung von Schriftarten

Rechtschreibung

Beispielprogramme und Shell-Sitzungen

Einzug bei Struktur-Definitionen, Protokollen von Shell-Sitzungen usw.

BEISPIEL

SIEHE AUCH

KOLOPHON

ÜBERSETZUNG