MAN-PAGES(7)

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

ÜBERSICHT
man [Abschnitt] Titel

BESCHREIBUNG
Diese Seite beschreibt die Konventionen, die Sie einhalten sollten, wenn Sie Handbuchseiten für das Projekt »Linux man-pages« schreiben, das die vom Linux-Kernel und der GNU C-Bibliothek bereitgestellte API auf Anwendungsebene dokumentiert. Das Projekt pflegt die Linux-Handbuchseiten des Abschnitts 2 sowie viele der Seiten in den Abschnitten 3, 4, 5 und 7. Die hier beschriebenen Konventionen können auch für die Autoren der Handbuchseiten anderer Projekte von Nutzen sein.

  Gliederung der Handbuchseiten

Die Handbuchseiten sind traditionell in die folgenden Abschnitte eingeteilt:

1 Commands (Programs)
    Diese Befehle kann ein Benutzer in der Shell ausführen.

2 System calls
    Diese Funktionen müssen vom Kernel ausgeführt werden.

3 Library calls
    die Mehrzahl der Libc-Funktionen

4 Special files (devices)
    die Dateien in /dev

5 File formats and conventions
    die Formate von /etc/passwd und weiteren menschenlesbaren Dateien

6 Games

7 Overview, conventions, and miscellaneous
    Überblick über verschiedene Themen, Konventionen und Protokolle, Zeichensatz-Standards und diverse andere Dinge

8 System management commands
    Dazu gehören Befehle wie mount(8). Viele davon können nur mit Administratorrechten ausgeführt werden.

  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 die 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 eingebettet eingereicht werden. Neue Sätze sollten in 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 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 werden sollte (z. B. 7)

    Datum
        The date of the last nontrivial change that was made to the man page. (Within the man-pages project, the necessary updates to these timetamps are handled automatically by scripts, so there is no need to manually update them as part of a patch.) Dates should be written in the form YYYY-MM-DD.

    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 Programmer's Manual.

  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.
NAME
SYNOPSIS
CONFIGURATION       [im Allgemeinen nur in Abschnitt 4]
DESCRIPTION
OPTIONS             [im Allgemeinen nur in den Abschnitten 1, 8]
EXIT STATUS         [im Allgemeinen nur in den Abschnitten 1 und 8]
RETURN VALUE        [im Allgemeinen nur in den Abschnitten 2 und 3]
ERRORS              [typischerweise nur in den Abschnitten 2 und 3]
ENVIRONMENT
FILES
ATTRIBUTES          [im Allgemeinen nur in den Abschnitten 2 und 3]
VERSIONS            [im Allgemeinen nur in den Abschnitten 2 und 3]
cONFORMING TO
NOTES
BUGS
EXAMPLE
SEE ALSO
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
    Der Name der Handbuchseite. Lesen Sie man(7) für wichtige Hinweise zu der/den Zeile(n), die dem Befehl .SH NAME folgen sollten. Alle Wörter in dieser Zeile (darunter auch das Wort, das unmittelbar auf das »\-« folgt) sollten kleingeschrieben werden, außer wenn das Englische oder die Gepflogenheiten der Fachbegriffe es anders vorschreiben.

SYNOPSIS
    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, dass der Text genau so eingegeben werden muss, austauschbare Argumente werden durch Kursivschrift gekennzeichnet. Klammern ([]) umgeben optionale Argumente, senkrechte Striche (|) trennen Elemente, von denen eines 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 SYNOPSIS angegeben werden. Wie es gemacht wird, ist in feature_test_macros(7) beschrieben.

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

DESCRIPTION
    erklärt die Wirkungsweise des Programms, der Funktion oder des Formats. Legen Sie die Interaktion mit Dateien und der Standardeingabe dar 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. Achten Sie darauf, bei der Beschreibung eines neuen Verhaltens oder eines neuen Schalters für einen Systemaufruf oder eine Bibliotheksfunktion die Kernel- oder C-Bibliotheksversion anzugeben, bei der diese Änderung eingeführt wurde. Die bevorzugte Methode, auf diese Information hinzuweisen, ist bei Schaltern als Teil einer .TP-Liste, in der folgenden Form (hier für einen neuen Schalter eines Systemaufrufes):

    XYZ_FLAG (seit Linux 3.7)
        Beschreibung des Schalters …

    Die Versionsinformation anzugeben ist besonders hilfreich für Benutzer, die auf eine ältere Kernel- oder C-Bibliotheksversion angewiesen sind (dies ist zum Beispiel bei eingebetteten Systemen typisch).

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

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

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

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

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

ATTRIBUTES
    Eine in Abschnitte unterteilte Zusammenfassung der verschiedenen Attribute von Funktionen, die auf dieser Seite dokumentiert sind. Die folgenden Unterabschnitte sind definiert:

    Multithreading (see pthreads(7))
        Dieser Unterabschnitt behandelt Attribute, die sich auf multithread-fähige Anwendungen beziehen:

        *   Ob die Funktion multithread-fähig ist.

        *   Ob die Funktion ein Abbruchpunkt ist.

        *   Ob die Funktion async-cancel-safe ist.

        Details zu diesen Attributen finden Sie in pthreads(7).

VERSIONS
    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 VERSIONS-Abschnitt in der Handbuchseite enthalten sollte. 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 für Kernel-Schnittstellen interessant sein, 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 Ä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.

CONFORMING TO
    Dieser Abschnitt beschreibt alle Normen oder Konventionen, die Funktionen oder Befehle betreffen, die auf den Handbuchseiten beschrieben werden. Die bevorzugten Ausdrücke für die verschiedenen Standards sind als Überschriften in standards(7) aufgeführt. Für eine Handbuchseite in Abschnitt 2 oder 3 sollte(n) 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 um 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 diese Systeme. 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 ('.').

NOTES
    enthält verschiedene Anmerkungen. Für Handbuchseiten der Abschnitte 2 und 3 könnten die Unterabschnitte (SS) Linux Notes und Glibc Notes nützlich sein.

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

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

AUTHORS
    gibt die Autoren der Dokumentation oder des Programms an. Von einem AUTHORS-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 die 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.

SEE ALSO
    enthält eine durch Kommata gegliederte Liste thematisch 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.

    Wenn die »SEE ALSO«-Liste viele lange Namen von Handbuchseiten enthält, kann es zur Verbesserung der visuellen Darstellung sinnvoll sein, die Anweisungen .ad l (nicht rechts anordnen) und .nh (keine Silbentrennung) zu verwenden. Die Silbentrennung individueller Seitennamen können Sie vermeiden, indem Sie den Wörtern die Zeichenkette »\%« voranstellen.

STIL-RICHTLINIEN
Die folgenden Unterabschnitte beschreiben den bevorzugten Stil für das Projekt man-pages. Im Folgenden nicht erwähnte Details finden Sie möglicherweise im Chicago Manual of Style. Versuchen sie auch, im Verzeichnisbaum des Projekts nach bereits vorhandenen Beispielen bestimmter Anwendungsfälle zu suchen.

  Geschlechtsneutrale Begriffswahl
Verwenden Sie, soweit möglich, eine geschlechtsneutrale Schreibweise in den Texten Ihrer Handbuchseiten. Die Verwendung von »they« (»them«, »themself«, »their«) als geschlechtsneutrales Pronomen für den Singular ist akzeptabel.

  Verwendung von Schriftarten

Funktionsargumente werden immer kursiv geschrieben, auch in SYNOPSIS. 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 Header-Dateien) werden immer kursiv gesetzt (z. B. <stdio.h>), außer in der SYNOPSIS, wo eingefügte Dateien fett geschrieben werden (z. B. #include <stdio.h>). Wenn Sie auf die Einbindung einer Standard-Header-Datei verweisen, setzen Sie die Header-Datei wie in C gebräuchlich in spitze 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, der eine Leerzeile vor- und nachgestellt wird, 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 sollten kursiv gesetzt werden, wenn Sie nicht auf einer separaten Zeile eingerückt geschrieben werden. Auch hier kann die Verwendung von geschützten Leerzeichen angezeigt sein, wenn der Ausdruck in den Fließ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 (das heißt, die Handbuchseite gehört zu den Abschnitten 2 oder 3), dann sollte dem Namen ein Paar 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 »\fB...\fP()« erleichtert die Entwicklung von Werkzeugen für die Auswertung von Handbuch-Quelltexten.

Jeder Verweis auf eine andere Handbuchseite sollte den Namen in Fettschrift darstellen und immer ohne Leerzeichen 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.) Steuerzeichen sollten in Fettschrift ohne Anführungszeichen geschrieben werden, beispielsweise ^X.

  Rechtschreibung
Seit Release 2.39 folgen die man-pages der amerikanischen Rechtschreibung (vorher bestanden sie aus einer zufälligen Mischung aus britischer und amerikanischer Rechtschreibung). Bitte verfassen Sie alle neuen Seiten und Patches nach diesen Konventionen. Abgesehen von den gut bekannten Rechtschreibunterschieden gibt es ein paar weitere Feinheiten, auf die Sie achten sollten:

*   Amerikanisches Englisch tendiert zu den Formen »backward«, »upward«, »toward« und so weiter, während im britischen Englisch eher »backwards«, »upwards«, »towards«, und so weiter verwendet werden.

  BSD-Versionsnummern
Das klassische Schema zum Schreiben von BSD-Versionsnummern lautet x.yBSD, wobei x.y die Versionsnummer ist (z.B. 4.2BSD). Vermeiden Sie Formen der Art BSD 4.3.

  Großschreibung
In den Überschriften der Unterabschnitte (»SS«) schreiben Sie das erste Wort groß, die anderen Wörter dagegen nicht, es sei denn, die Konventionen der englischen Sprache (zum Beispiel Eigennamen) oder Erfordernisse der Programmiersprache (zum Beispiel Identifizierernamen) erzwingen die Abweichung von dieser Regel. Beispiel: .SS Unicode under Linux

  Einzug bei Strukturdefinitionen, Protokollen von Shell-Sitzungen und so weiter.
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).

  Bevorzugte Begriffe
Die folgende Tabelle führt einige bevorzugte Begriffe auf, die in Handbuchseiten verwendet werden sollten, hauptsächlich um Konsistenz innerhalb der Sammlung der Handbuchseiten sicherzustellen.
Begriff | Nicht verwenden | Anmerkungen
bit mask | bitmask
built-in | builtin
Epoch | epoch | Für den Beginn der UNIX-Zeitrechnung (00:00:00, 1. Januar 1970 UTC)
filename | file name
filesystem | file system
hostname | host name
inode | i-node
lowercase | lower case, lower-case
pathname | path name
pseudoterminal | pseudo-terminal
privileged port | reserved port, system port
real-time | realtime, real-time
run time | runtime
saved set-group-ID | saved group ID, saved set-GID
saved set-user-ID | saved user ID, saved set-UID
set-group-ID | set-GID, setgid
set-user-ID | set-UID, setuid
superuser | super user, super-user
superblock | super block, super-block
timestamp | time stamp
timezone | time zone
uppercase | upper case, upper-case
usable | useable
user space | userspace
username | user name
zeros | zeroes

Siehe auch den nachfolgenden Abschnitt Bindestriche in attributiven Zusammensetzungen.

  Zu vermeidende Ausdrücke
Die folgende Tabelle führt einige Ausdrücke (zusammen mit Alternativen) auf, die in Handbuchseiten vermieden werden sollten, hauptsächlich um Konsistenz innerhalb der Sammlung der Handbuchseiten sicherzustellen.
Vermeiden | Stattdessen | Anmerkungen
32bit | 32-bit | ebenfalls für 8-bit, 16-bit usw.
current process | calling process | Ein häufiger Fehler der Kernel-Programmierer beim Schreiben von Handbuchseiten
manpage | man page, manual page
minus infinity | negative infinity
non-root | unprivileged user
non-superuser | unprivileged user
nonprivileged | unprivileged
OS | operating system
plus infinity | positive infinity
pty | pseudoterminal
tty | terminal
Unices | UNIX systems
Unixes | UNIX systems

  Geschützte Marken
Verwenden Sie die korrekte Schreibweise für geschützte Marken. Nachfolgend finden Sie eine Liste der korrekten Schreibweisen diverser relevanter Marken, die gelegentlich falsch geschrieben werden:
     DG/UX
     HP-UX
     UNIX
     UnixWare

  NULL, NUL, Null-Zeiger und Null-Zeichen
Ein null pointer ist ein Zeiger, der auf nichts verweist. Er wird normalerweise durch die Konstante NULL angegeben. Andererseits bezeichnet NUL das Null-Byte, ein Byte mit dem Wert 0, das in C durch die Zeichenkonstante '\0' ausgedrückt wird. Der bevorzugte Begriff für den Zeiger ist »null pointer« oder einfach »NULL«, bitte schreiben Sie nicht »NULL pointer«. Der bevorzugte Begriff für das Byte ist »null byte«. Bitte schreiben Sie nicht »NUL«, da es zu leicht mit »NULL« verwechselt werden kann. Vermeiden Sie auch die Begriffe »zero byte« und »null character«. Das Byte, das eine C-Zeichenkette beendet, sollte als »the terminating null byte« beschrieben werden. Zeichenketten können als »null-terminated« bezeichnet werden, vermeiden Sie dagegen »NUL-terminated«.

  Hyperlinks
Verwenden Sie für Hyperlinks das Makropaar .UR/.UE (siehe groff_man(7)). Dieses erzeugt intakte Hyperlinks, die in einem Webbrowser geöffnet werden können, wenn die Seite etwa folgendermaßen gerendert wird:
     BROWSER=firefox man -H Seitenname

  Verwendung von e.g., i.e., etc., a.k.a. und ähnlichem
Im Allgemeinen sollten Abkürzungen wie »e.g.«, »i.e.«, »etc.«, »a.k.a.« vermieden werden. Schreiben Sie die Wörter stattdessen aus: »for example«, »that is«, »and so on«, »also known as«. Die einzige Stelle, wo solche Abkürzungen akzeptabel sind, ist in kurzen in Klammern gesetzten Anmerkungen (z.B. wie in dieser hier). Verwenden Sie stets Punkte in solchen Abkürzungen, wie hier gezeigt. Zusätzlich sollte auf »e.g.« und »i.e.« stets ein Komma folgen.

  Em-Dashes
Einen em-Gedankenstrich (emdie Glyphe, die zu beiden Enden dieses Satzteiles steht setzen Sie (emin *roff mit dem Makro »\«. (Auf einem ASCII-Terminal wird ein em-Gedankenstrich üblicherweise als zwei Bindestriche, in anderen typografischen Kontexten als langer Gedankenstrich dargestellt.) Em-Gedankenstriche sollten ohne vor- und nachstehendes Leerzeichen geschrieben werden.

  Bindestriche in attributiven Zusammensetzungen
Zusammengesetzte Begriffe sollten mit Bindestrich geschrieben werden, wenn Sie als Attribut verwendet werden, zum Beispiel, um ein nachfolgendes Nomen näher zu bestimmen. Einige Beispiele:
    32-bit value
    command-line argument
    floating-point number
    run-time check
    user-space function
    wide-character string

  Zusammensetzungen mit multi, non, pre, re, sub, usw.
Die allgemeine Tendenz im modernen Englisch ist es, nach Präfixen wie »multi«, »non«, »pre«, »re« oder »sub« keinen Bindestrich zu setzen. Die Handbuchseiten sollten generell dieser Regel folgen, wenn diese Präfixe in nativen englischen Konstrukten mit einfachen Suffixen verwendet werden. Die folgende Liste zeigt einige Beispiele der bevorzugten Formen:
    interprocess
    multithreaded
    multiprocess
    nonblocking
    nondefault
    nonempty
    noninteractive
    nonnegative
    nonportable
    nonzero
    preallocated
    precreate
    prerecorded
    reestablished
    reinitialize
    rearm
    reread
    subcomponent
    subdirectory
    subsystem Bindestriche sollten gesetzt werden, wenn die Präfixe in Wörtern verwendet werden, die nicht zum englischen Standardwortschatz gehören, wie geschützte Marken, Eigennamen, Akronyme oder zusammengesetzte Begriffe. Einige Beispiele:
    non-ASCII
    non-English
    non-NULL
    non-real-time Beachten Sie auch, dass »re-create« und »recreate« zwei Verben unterschiedlicher Bedeutung sind. Das erstere dürfte vermutlich jenes sein, was Sie benötigen.

  Echtes Minuszeichen
Wo ein echtes Minus-Zeichen benötigt wird, zum Beispiel für die Zahl -1 oder bei Optionen mit einem vorangestellten Dash, wie in ls -l, verwenden Sie die folgende Form im Quelltext der Handbuchseite:
    \- Diese Richtlinie gilt auch für Code-Beispiele.

  Zeichenkonstanten
Um einfache Zitatzeichen zu verwenden, die sowohl in ASCII als auch in UTF-8 korrekt dargestellt werden können, schreiben Sie Zeichenkonstanten im Quelltext der Handbuchseite in der folgenden Form:
    \(aqC\(aq wobei C das zitierte Zeichen ist. Diese Richtlinie ist auch auf Zeichenkonstanten und in code-Beispielen anzuwenden.

  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 Textbeschreibung 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!)

*   Aus Konsistenzgründen sollten alle Beispielprogramm mit einer der folgenden Sequenzen beendet werden:
         exit(EXIT_SUCCESS);
         exit(EXIT_FAILURE); Vermeiden Sie die folgenden Formen, um ein Programm zu beenden:
        exit(0);
        exit(1);
        return n;

*   If there is extensive explanatory text before the program source code, mark off the source code with a subsection heading Program source, as in: .SS Program source Tun Sie dies immer, wenn der erklärende Text ein Sitzungsprotokoll der Shell enthält.

Wenn Sie eine Shell-Sitzung einfügen, welche die Verwendung eines Programms oder andere Möglichkeiten des Systems demonstriert:

*   Setzen Sie das Sitzungsprotokoll vor die Quellcode-Auflistung.

*   Rücken Sie das Sitzungsprotokoll um vier Zeichen ein.

*   Wählen Sie Fettschrift für vom Benutzer eingegebenen Text, um ihn von der vom System erzeugten Ausgabe zu unterscheiden.

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

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.70 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, 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>, Helge Kreutzmann <debian@helgefjell.de>, Stephan Beck <tlahcuilo@gmx.net> und Mario Blättermann <mario.blaettermann@gmail.com> 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>.