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

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 meisten Linux-Handbuchseiten des Abschnitts 2, viele der Seiten in den
Abschnitten 3, 4 und 7 sowie einige Seiten in den Abschnitten 1, 5 und 8. 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 User commands (Programs)
Befehle, die ein Benutzer in der Shell ausführen kann.

2 System calls
Funktionen, die vom Kernel ausgeführte Aktionen umhüllen (»wrap«).

3 Library calls
Alle Bibliotheksfunktionen außer den Systemaufruf-Wrappern (die meisten der
libc-Funktionen).

4 Special files (devices)
Dateien, die in /dev liegen und den Zugriff auf Geräte über den Kernel erlauben.

5 File formats and configuration files
Beschreibt verschiedene menschenlesbare Dateiformate und Konfigurationsdateien.

6 Games
Auf dem System verfügbare Spiele und lustige kleine Programme.

7 Overview, conventions, and miscellaneous
Überblicke oder Beschreibungen verschiedener Themen, Konventionen und Protokolle,
Zeichensatz-Standards, dem Standard-Dateisystemlayout und diversen anderen Dingen.

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 an.tmac von groff 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.

Titelzeile
Der erste Befehl einer Handbuchseite sollte ein TH-Befehl sein:

.TH Titel Abschnitt Datum Quelle Handbuchabschnitt

Die Argumente dieses Befehls sind wie folgt:

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 Das Datum der letzten nicht trivialen Änderung, die an der Handbuchseite
vorgenommen wurde. (Innerhalb des Projekts man-pages werden die notwendigen
Aktualisierungen dieser Zeitstempel automatisch durch Skripte erledigt, daher ist
eine händische Aktualisierung als Teil des Patches nicht notwendig.) Daten sollten
in der Form YYYY-MM-DD geschrieben werden.

Quelle Name und Version des Projekts, von welchem die Handbuchseite bereitgestellt wird
(was nicht zwangsläufig das Paket sein muss, welches die Funktionalität
bereitstellt).

Handbuchabschnitt
Normalerweise sollte dies leer sein, da der Standardwert eine gute Wahl ist.

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
BIBLIOTHEK [in der Regel nur in den Abschnitten 2 und 3]
SYNOPSIS
KONFIGURATION [in der Regel nur in Abschnitt 4]
DESCRIPTION
OPTIONEN [in der Regel nur in den Abschnitten 1 und 8]
EXIT-STATUS [in der Regel nur in den Abschnitten 1 und 8]
RÜCKGABEWERT [in der Regel nur in den Abschnitten 2 und 3]
FEHLER [typischerweise nur in den Abschnitten 2 und 3]
UMGEBUNGSVARIABLEN
DATEIEN
VERSIONEN [in der Regel nur in den Abschnitten 2 und 3]
ATTRIBUTE [in der Regel nur in den Abschnitten 2 und 3]
STANDARDS
ANMERKUNGEN
EINSCHRÄNKUNGEN
FEHLER
BEISPIELE
AUTOREN [wird nicht empfohlen]
FEHLER MELDEN [wird in man-pages nicht verwendet]
COPYRIGHT [wird in man-pages nicht verwendet]
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 dieser Handbuchseiten

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.

LIBRARY
Die Bibliothek, die ein Symbol bereitstellt.

Hier wird der allgemeine Name der Bibliothek angezeigt, sowie in Klammern der Name
der Bibliotheksdatei und, falls erforderlich, den Linker-Schalter, um ein Programm
dagegen zu linken: (libfoo[, -lfoo]).

SYNOPSIS
Eine kurze Zusammenfassung des Befehls oder der Funktionsschnittstelle

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
Eine Bescheibung der Funktionsweise 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
Eine Beschreibung der 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
Eine Liste der möglichen Werte für den Exit-Status eines Programms und die
Umstände, die zur Rückgabe dieser Werte führen

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.

Wenn mehrere unterschiedliche Umstände den gleichen Fehler erzeugen, wird
bevorzugt, dass verschiedene Listeneinträge (mit gedoppelten Fehlernamen) für jeden
dieser Umstände erstellt werden. Dadurch werden die unterschiedlichen Umstände
deutlicher, die Liste einfacher zu lesen und dies erlaubt es, Metainformationen
(z.B. Kernelversionsnummern, unter denen die Umstände erstmals zum Tragen kamen)
leichter für jeden Umstand zu markieren.

Die Fehlerliste sollte alphabetisch sortiert sein.

ENVIRONMENT
Eine Liste aller Umgebungsvariablen, die auf das Programm einwirken mit
Erläuterung, was sie bewirken.

FILES Eine Liste aller Dateien, die das Programm oder die Funktion verwenden, wie
Konfigurationsdateien, Einrichtungsdateien und Dateien, auf denen das Programm
direkt arbeitet

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 Zusammenfassung der verschiedenen Attribute von Funktionen, die auf dieser
Seite dokumentiert sind. Siehe attributes(7) für weitere Details.

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

STANDARDS
Eine Beschreibung aller Standards oder Konventionen, die die Funktionen oder den
Befehle betrifft, die durch die Handbuchseite beschrieben wird.

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

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 Verschiedene Anmerkungen

Für Handbuchseiten der Abschnitte 2 und 3 könnten die Aufnahme von Unterabschnitten
(SS) Linux Notes und Glibc Notes nützlich sein.

In Abschnitt 2 verwenden Sie die Überschrift C library/kernel differences, um
Abschnitte zu markieren, die die Unterschiede (falls vorhanden) zwischen der
C-Bibliothek-Wrapper-Funktion für einen Systemaufruf und der rohen
Systemaufrufschnittstelle durch den Kernel beschreiben.

CAVEATS
Warnungen für typische fehlerhafte Anwendungen einer API, die jedoch keinen
API-Fehler oder Designfehler hervorrufen.

BUGS Eine Liste von Einschränkungen, bekannten Mängeln oder Unannehmlichkeiten und
weiteren fragwürdigen Verhalten.

EXAMPLES
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
Eine Liste der Autoren der Dokumentation oder des Programms

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.

REPORTING BUGS
Das Projekt man-pages verwendet keinen Abschnitt REPORTING BUGS in den
Handbuchseiten. Informationen zum Melden von Fehlern werden stattdessen in dem per
Skript erzeugten Abschnitt COLOPHON bereitgestellt. Dennoch verwenden verschiedene
Projekte einen Abschnitt REPORTING BUGS. Es wird empfohlen, diesen nahe dem Ende
der Seite zu platzieren.

COPYRIGHT
Das Projekt man-pages verwendet keinen Abschnitt COPYRIGHT in den Handbuchseiten.
Urheberrechtliche Informationen werden stattdessen im Seitenquelltext gepflegt. In
Seiten, die diesen Abschnitt verwenden, wird empfohlen, diesen nahe dem Ende der
Seite direkt oberhalb von SEE ALSO zu platzieren.

SEE ALSO
Eine durch Kommata gegliederte Liste thematisch verwandter Handbuchseiten; manchmal
folgen weitere Handbuchseiten oder Dokumente mit inhaltlichem Bezug.

Die Liste sollte nach Abschnittsnummern und in den Abschnitten alphabetisch
sortiert werden. 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.

Aufgrund der autonomen und verteilten Natur von FOSS-Projekten und ihrer
Dokumentation ist es manchmal notwendig – und in vielen Fällen wünschenswert –,
dass der Abschnitt »SIEHE AUCH« Referenzen auf Handbuchseiten von anderen Projekten
enthält.

KONVENTIONEN ZU WORTWAHL UND FORMATIERUNG

       In   den  folgenden  Unterabschnitten  finden  Sie  einige  Details  für  die  bevorzugten
       Formatierungs- und Wortwahlkonventionen in den verschiedenen  Abschnitten  der  Seiten  im
       man-pages-Projekt.

   ÜBERSICHT
       Brechen Sie Funktionsprototypen in einem .nf/.fi-Paar um, damit Auffüllung vermieden wird.

       Im  Allgemeinen  sollten Sie immer, wenn im Abschnitt SYNOPSIS mehrere Funktionsprototypen
       aufgeführt sind, diese nicht durch Leerzeilen trennen. Jedoch dürfen Leerzeilen (mit  .PP)
       in folgenden Fällen hinzugefügt werden:

       •  um  lange  Listen  von  Funktionsprototypen  in  logische  Gruppen  zu unterteilen (ein
          Beispiel finden Sie in list(3));

       •  in anderen Fällen, wo dies die Lesbarkeit verbessert.

       Im Abschnitt SYNOPSIS darf ein langer Funktionsprototyp in der nächsten Zeile  fortgesetzt
       werden. Der Einzug der Fortsetzungszeile geschieht nach den folgenden Regeln:

       (1)  Falls  eine  einzelne  Zeile eines solchen Prototyps fortgesetzt werden muss, richten
            Sie  die  Fortsetzungszeile  so  aus,  dass  später  bei  der  Darstellung  in  einer
            dicktengleichen  Schrift  (zum  Beispiel in einem xterm) die Fortsetzungszeile direkt
            unter dem Anfang der Argumentliste eine Zeile darüber beginnt.  Eine  Ausnahme  wäre,
            wenn der der Funktionsprototyp sehr lang ist und der Einzug notfalls angepasst werden
            muss, um eine sehr lange  oder  eine  weitere  Fortsetzungszeile  zu  vermeiden.  Ein
            Beispiel:

                int tcsetattr(int fd, int optional_actions,
                              const struct termios *termios_p);

       (2)  Sollten  aber  mehrere  Funktionen im Abschnitt SYNOPSIS Fortsetzungszeilen erfordern
            und die Funktionsnamen unterschiedlich lang sein, richten Sie die  Fortsetzungszeilen
            so  aus,  dass  sie  alle in der gleichen Spalte beginnen. Dadurch ergibt sich in der
            PDF-Ausgabe eine wesentlich  bessere  Darstellung,  da  der  SYNOPSIS-Abschnitt  eine
            Schrift  variabler  Breite verwendet, wodurch Leerzeichen schmaler dargestellt werden
            als die meisten anderen Zeichen. Ein Beispiel:

                int getopt(int argc, char * const argv[],
                           const char *optstring);
                int getopt_long(int argc, char * const argv[],
                           const char *optstring,
                           const struct option *longopts, int *longindex);

   RÜCKGABEWERT
       Die bevorzugte Formulierung für das Setzen von errno ist »errno is  set  to  indicate  the
       error« oder ähnlich. Diese Formulierung ist zu denen in POSIX.1 und FreeBSD konsistent.

   ATTRIBUTE
       Beachten Sie Folgendes:

       •  Brechen Sie die Tabelle in diesem Abschnitt in ein .ad l/.ad-Paar um, um Textauffüllung
          zu vermeiden, und ein .nh/.hy-Paar, um die Silbentrennung zu verhindern.

       •  Stellen Sie sicher, dass die Tabelle die gesamte Seitenbreite einnimmt, indem Sie  eine
          lbx-Beschreibung  für  eine  der  Spalten verwenden (normalerweise die erste Spalte, in
          einigen Fällen jedoch die letzte Spalte, falls sie viel Text enthält).

       •  Verwenden  Sie  so  viele  T{/T}-Makro-Paare  wie  möglich,  um  damit  Zeilen  in  den
          Tabellenzellen umzubrechen. Denken Sie auch daran, dass Seiten gelegentlich mit weniger
          als 80 Zeichen Breite dargestellt werden.

       Beispiele für alles vorstehend Aufgeführte finden Sie im Quelltext diverser Seiten.

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.

Konventionen für die Formatierung von Handbuchseiten, die Befehle beschreiben
Bei Handbuchseiten, die einen Befehl beschreiben (typischerweise in Abschnitt 1 und 8),
werden die Argumente immer in kursiv spezifiziert, selbst im Abschnitt SYNOPSIS.

Der Name des Befehls und seine Optionen sollten stets fett formatiert werden.

Konventionen für die Formatierung von Handbuchseiten, die Funktionen beschreiben
Bei Handbuchseiten, die Funktionen beschreiben (typischerweise in Abschnitt 2 und 3),
werden die Argumente immer in kursiv spezifiziert, selbst im Abschnitt SYNOPSIS, wobei der
Rest der Funktion in fett spezifiziert wird:

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

Variablennamen sollten wie die Namen von Argumenten kursiv geschrieben werden.

Jeder Hinweis auf den Gegenstand der aktuellen Handbuchseite sollte mit diesem Namen in
Fettschrift geschrieben werden, gefolgt von einem Paar Klammern in Normalschrift (Roman).
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.

Semantische Zeilenvorschübe verwenden
Im Quelltext einer Handbuchseite sollten neue Sätze in einer neuen Zeile beginnen und
lange Sätze an Interpunktionszeichen, welche die Satzteile voneinander abgrenzen (Komma,
Semikolon, Doppelpunkt usw.), geteilt werden. Lange Satzteile sollten an Phrasengrenzen
geteilt werden. Diese Konvention, im englischen zuweilen »Semantic newlines« (semantische
Zeilenvorschübe) genannt, erleichtert es, die Wirkung von Patches zu beurteilen, welche
oft auf Ebene einzelner Sätze, Satzteile oder Phrasen arbeiten.

Listen
Es gibt verschiedene Arten von Listen:

Markierte Absätze
Diese werden für eine Liste von Markierungen und deren Beschreibungen verwendet.
Wenn die Markierungen Konstanten sind (entweder Makros oder Zahlen), werden diese
in Fettschrift gesetzt. Verwenden Sie das Makro .TP.

Ein Beispiel ist dieser »Markierte Absätze«-Unterabschnitt selbst.

Geordnete Listen
Den Elementen wird eine Zahl in Klammern vorangestellt (»(1)«, »(2)« …). Diese
repräsentieren eine geordnete Abfolge von Schritten.

Wenn es Teilschritte gibt, werden diese in der Form »(4.2)« nummeriert.

Positionale Listen
Den Elementen wird eine Zahl (Index) in eckigen Klammern vorangestellt (»[1]«,
»[2]« …). Diese repräsentieren Felder in einer Menge. Der erste Index wird
Folgendes sein:

0 … wenn es Felder in einer C-Datenstruktur repräsentiert, um Konsistenz mit
Arrays zu gewährleisten.
1 … wenn es Felder in einer Datei repräsentiert, um Konsistenz mit Werkzeugen
wie cut(1) zu gewährleisten.

Auswahllisten
Den Elementen wird ein Buchstabe in Klammern vorangestellt (»(a)«, »(b)« …). Diese
repräsentieren eine Reihe von sich (normalerweise) gegenseitig ausschließenden
Alternativen.

Aufzählungslisten
Den Elementen wird ein Aufzählungszeichen vorangestellt (\[bu]). Alles, was sich
nicht anderweitig kategorisieren lässt, kann in einer solchen Liste dargestellt
werden.

Nummerierte Hinweise
Obwohl nicht wirklich als Liste zu betrachten, ist die Syntax identisch zu der der
»Positionalen Listen«.

Zwischen dem Listensymbol und den Elementen sollten stets zwei Leerzeichen gesetzt werden.
Dies bezieht sich nicht auf »Markierte Absätze«, welche den vorgegebenen Regeln für die
Einrückung folgen.

Formatierungskonventionen (Allgemeines)
Absätze sollten mit geeigneten Markierungen voneinander getrennt werden (üblicherweise
entweder .PP oder .IP). Trennen Sie Absätze nicht durch Einfügen von Leerzeilen, da diese
Darstellungsfehler in einigen Ausgabeformaten verursachen (wie PostScript und PDF).

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.

Bei der Angabe von Shell-Sitzungen sollte die Benutzereingabe stets fett formatiert
werden, bespielsweise

$ date
Do Jul 7 13:01:27 CEST 2016

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.

• Hinsichtlich »acknowledgement« bzw. »acknowledgment« gehen die Meinungen auseinander.
Letzteres dominiert, wird aber im amerikanischen Englisch nicht universell verwendet.
POSIX und die BSD-Lizenz verwenden die erstgenannte Schreibweise. Im
Linux-man-pages-Projekt verwenden wir »acknowledgement«.

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), formatieren Sie sie mittels der Makros .EX und .EE und schließen Sie
sie mit geeigneten Absatzmarkierungen (entweder .PP oder .IP) ein. Beispiel:

.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP

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 Hinweise
───────────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch Für den Beginn der
UNIX-Zeitrechnung
(00:00:00, 1.
Januar 1970 UTC)
Dateiname file name
Dateisystem file system
Rechnername host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
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
symbolic link symlink
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
x86-64 x86_64 Außer beim Verweis
auf das Ergebnis
von »uname -m« oder
ähnlichem
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 Hinweise
──────────────────────────────────────────────────────────────────

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-Byte
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 dargestellt 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.«, »cf.« und »a.k.a.«
vermieden werden. Schreiben Sie die Wörter stattdessen aus: »for example«, »that is«, »and
so on«, »compare to«, »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-Gedankenstriche
Einen em-Gedankenstrich – das Zeichen, das an beiden Enden dieses Satzteiles steht –,
setzen Sie in *roff mit dem Makro »\[em]«. (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.

Erzeugen optimaler Glyphen
Wo ein echtes Minus-Zeichen benötigt wird, zum Beispiel für die Zahl -1, für
Kreuzreferenzen zu anderen Handbuchseiten wie utf-8(7) oder bei Optionen mit einem
vorangestelltem Bindestrich, wie in ls -l, verwenden Sie die folgende Form im Quelltext
der Handbuchseite:

Diese Richtlinie gilt auch für Code-Beispiele.

Die Verwendung des echten Minuszeichens erfüllt die folgenden Zwecke:

• Verbesserung der Darstellung für verschiedene Ziele. Dies gilt insbesondere für die
PDF-Ausgabe und Terminals, die Unicode/UTF-8 darstellen können, allerdings nicht für
reine ASCII-Terminals.

• Erzeugen von Glyphen, die beim Kopieren von dargestellten Seiten beim Einfügen in ein
Terminal echte Minuszeichen erzeugen.

Um einfache Anführungszeichen zu verwenden, die in ASCII, in UTF-8 und in PDF korrekt
dargestellt werden können, verwenden Sie »\[aq]« (»Apostroph-Zitatzeichen«); zum Beispiel

\[aq]C\[aq]

wobei C das zitierte Zeichen ist. Diese Richtlinie ist auch auf Zeichenkonstanten und in
code-Beispielen anzuwenden.

Wo ein korrektes Zirkumflex-Zeichen (^) benötigt wird, das sowohl im Terminal als auch im
PDF gut dargestellt wird, verwenden Sie »\[ha]«. Dies ist insbesondere in Beispielcode
erforderlich, um in der daraus erzeugten PDF-Darstellung ein ansehnliches Zirkumflex zu
erhalten.

Die Verwendung eines nackten »~«-Zeichens führt zu einer fehlerhaften Darstellung in PDF.
Verwenden Sie stattdessen »\[ti]«. Dies ist insbesondere in Beispielcode erforderlich, um
in der daraus erzeugten PDF-Darstellung eine ansehnliche Tilde zu erhalten.

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 idealerweise kurz sein (zum Beispiel können bereits weniger
als 100 Codezeilen ein gutes Beispiel darstellen), doch können in einigen Fällen
längere Programme nötig sein, um die Verwendung einer API korrekt zu veranschaulichen.

• Ausdrucksstarker Code ist sehr begrüßenswert.

• Kommentare sollten dort eingefügt werden, wo sie hilfreich sind. Vollständige Sätze in
freistehenden Kommentaren sollten durch einen Punkt abgeschlossen werden. Kein
abschließender Punkt sollte nach »tag«-Kommentaren gesetzt werden (zum Beispiel
Kommentare in einer Code-Zeile), da solche Kommentare eher kurze Phrasen und keine
kompletten Sätze sind.

• 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!) Der
folgende Befehl kann dazu verwandt werden, Ihren Quellcode ähnlich dem bevorzugten Stil
zu formatieren:

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c

• 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;

• Falls ein umfangreicher erklärender Text vor dem Programm-Quellcode steht, markieren
Sie den Quellcode mit der Zwischenüberschrift Program source, wie 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.

BEISPIELE

       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), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)

ÜBERSETZUNG

       Die  deutsche  Übersetzung  dieser  Handbuchseite  wurde  von  Martin   Eberhard   Schauer
       <Martin.E.Schauer@gmx.de>,  Mario Blättermann <mario.blaettermann@gmail.com>, Stephan Beck
       <tlahcuilo@gmx.net>,  Dr.  Tobias  Quathamer  <toddy@debian.org>  und   Helge   Kreutzmann
       <debian@helgefjell.de> erstellt.

       Diese  Übersetzung  ist  Freie  Dokumentation;  lesen  Sie  die GNU General Public License
       Version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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 die Mailingliste der Übersetzer ⟨debian-l10n-german@lists.debian.org⟩.