Ubuntu Manpage: man-pages - Konventionen für das Schreiben von Linux-Handbuchseiten

BEZEICHNUNG

       man-pages - Konventionen für das Schreiben von Linux-Handbuchseiten

ÜBERSICHT

       man [Abschnitt] Titel

BESCHREIBUNG

This page describes the conventions that should be employed when writing man pages for the
Linux man-pages project, which documents the user-space API provided by the Linux kernel
and the GNU C library. The project thus provides most of the pages in Section 2, as well
as many of the pages that appear in Sections 3, 4, 5, and 7 of the man pages on a Linux
system. The conventions described on this page may also be useful for authors writing man
pages for other projects.

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 Überblick, 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
Neue Handbuchseiten sollten das in man(7) beschriebene Paket groff an.tmac verwenden.
Diese Wahl dient vor allem der Konsistenz: die überwiegende Mehrheit der existierenden
Linux-Handbuchseiten wird mit diesen Makros formatiert.

Konventionen für die Gestaltung der Quelltexte
Bitte beschränken Sie Zeilenlänge im Quelltext, wo immer möglich, auf nicht mehr als etwa
75 Zeichen. So werden Zeilenumbrüche durch verschiedene E-Mail-Clients vermieden, wenn
Patches inline eingereicht werden.

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
Der erste Befehl in einer Handbuchseite sollte ein TH-Befehl sein:

.TH Titel Abschnitt Datum Quelle Handbuch

wobei:

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
Die folgende Liste enthält gebräuchliche und empfohlene Abschnitte. Die meisten
Handbuchseiten sollten mindestens die hervorgehobenen Abschnitte enthalten. Gliedern Sie
eine neue Handbuchseite so, dass die Abschnitte in der Reihenfolge der Liste platziert
werden.

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
ATTRIBUTE [im Allgemeinen nur in den Abschnitten 2 und 3]
VERSIONEN [im Allgemeinen nur in den Abschnitten 2 und 3]
KONFORM ZU
ANMERKUNGEN
FEHLER
BEISPIEL
SIEHE AUCH

Bitte verwenden Sie eine traditionelle Überschrift, wo sie zutreffen würde; diese Art von
Konsistenz kann die Informationen leichter verständlich machen. Wenn Sie müssen, können
Sie eigene Überschriften wählen, wenn die Dinge dadurch leichter zu verstehen sind. (Das
kann besonders für Seiten in den Abschnitten 4 und 5 nützlich sein.) Doch bevor Sie das
tun, prüfen Sie bitte, ob Sie auch traditionelle Überschriften verwenden können (und
innerhalb dieser Abschnitte einige Unterabschnitte (.SS) einfügen).

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

NAME The name of this manual page. See man(7) for important details of the
line(s) that should follow the .SH NAME command. All words in this line
(including the word immediately following the "\-") should be in lowercase,
except where English or technical terminological convention dictates
otherwise.

Ü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.

When describing new behavior or new flags for a system call or library
function, be careful to note the kernel or C library version that introduced
the change. The preferred method of noting this information for flags is as
part of a .TP list, in the following form (here, for a new system call
flag):

XYZ_FLAG (seit Linux 3.7)
Beschreibung des Schalters…

Including version information is especially useful to users who are
constrained to using older kernel or C library versions (which is typical in
embedded systems, for example).

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.

ATTRIBUTE A summary of various attributes of the function(s) documented on this page,
broken into subsections. The following subsections are defined:

Multithreading (see pthreads(7))
This subsection notes attributes relating to multithreaded
applications:

* Whether the function is thread-safe.

* Whether the function is a cancellation point.

* Whether the function is async-cancel-safe.

Details of these attributes can be found in pthreads(7).

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 ('.').

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.

Where the SEE ALSO list contains many long manual page names, to improve the
visual result of the output, it may be useful to employ the .ad l (don't
right justify) and .nh (don't hyphenate) directives. Hyphenation of
individual page names can be prevented by preceding words with the string
"\%".

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

Kurze Befehle können, kursiv gesetzt, in den laufenden Text aufgenommen werden; z. B. man
7 man-pages. In diesem Fall kann es sich lohnen, an geeigneten Stellen in der Befehlszeile
geschützte Leerzeichen ("\ ") zu verwenden. Befehlsoptionen sollten kursiv geschrieben
werden, z. B. -l.

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

Die Verwendung dieses Formats anstatt der Verwendung von »\fB...\fP()« erleichtert die
Entwicklung von Werkzeugen für die Auswertung von Handbuch-Quelltexten.

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).

(Die Angabe der Abschnittsnummer in Querverweisen ermöglicht es Werkzeugen wie man2html(1)
korrekte Hyperlinks zu erstellen.)

Rechtschreibung
Seit Release 2.39 folgen die man-pages der amerikanischen Rechtschreibung. Bitte verfassen
Sie alle neuen Seiten und Patches nach diesen Konventionen.

Großschreibung
In subsection ("SS") headings capitalize the first word in heading, but otherwise use
lower case, except where English usage (e.g., proper nouns) or programming language
requirements (e.g., identifier names) dictate otherwise.

Beispielprogramme und Shell-Sitzungen
Handbuchseiten können Beispielprogramme enthalten, die den Gebrauch von Systemaufrufen
oder Bibliotheksfunktionen beschreiben. Beachten Sie jedoch das Folgende:

* 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.
Wenn Struktur-Definitionen, Protokolle von Shell-Sitzungen, usw. im laufenden Text
eingefügt werden, rücken Sie diese um 4 Leerzeichen ein (d. h. umschließen Sie den Block
mit .in +4n und .in).

BEISPIEL

       Kanonische Beispiele für die Gestaltung von Handbuchseiten für  das  man-pages-Paket  sind
       pipe(2) und fcntl (2).

SIEHE AUCH

       man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)

KOLOPHON

       This  page  is  part  of release 3.54 of the Linux man-pages project. A description of the
       project,    and    information    about    reporting    bugs,    can    be    found     at
       http://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

       Die   deutsche   Übersetzung  dieser  Handbuchseite  wurde  von  Martin  Eberhard  Schauer
       <Martin.E.Schauer@gmx.de> erstellt.

       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>.