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

bezeichnung
übersicht
beschreibung
stil-richtlinien
beispiele
siehe auch
kolophon
übersetzung

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 Handbuch

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 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
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]
KONFORM ZU
ANMERKUNGEN
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.

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

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.

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. 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 oder Satzteile arbeiten.

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.

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

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

\(aqC\(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 und hilfreiche Kommentare sind sehr begrüßenswert.

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

KOLOPHON

       Diese Seite ist Teil der Veröffentlichung  5.10  des  Projekts  Linux-man-pages.  Eine  Beschreibung  des
       Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden
       sich unter https://www.kernel.org/doc/man-pages/.

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