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.
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.
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.
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.
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.
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.
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.
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«.
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.
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
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
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.
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 |
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 |
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«.
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
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.
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.
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 |
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.
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.
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)EN und pipe(2) finden Sie vorbildliche Beispielprogramme.