man-pages(7) Miscellaneous Information Manual man-pages(7) BEZEICHNUNG man-pages - Konventionen fur das Schreiben von Linux-Handbuchseiten UBERSICHT man [Abschnitt] Titel BESCHREIBUNG Diese Seite beschreibt die Konventionen, die Sie einhalten sollten, wenn Sie Handbuchseiten fur 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 konnen auch fur 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 ausfuhren kann. 2 System calls Funktionen, die vom Kernel ausgefuhrte Aktionen umhullen (>>wrap<<). 3 Library calls Alle Bibliotheksfunktionen ausser den Systemaufruf-Wrappern (die meisten der libc-Funktionen). 4 Special files (devices) Dateien, die in /dev liegen und den Zugriff auf Gerate uber den Kernel erlauben. 5 File formats and configuration files Beschreibt verschiedene menschenlesbare Dateiformate und Konfigurationsdateien. 6 Games Auf dem System verfugbare Spiele und lustige kleine Programme. 7 Overview, conventions, and miscellaneous Uberblicke oder Beschreibungen verschiedener Themen, Konventionen und Protokolle, Zeichensatz-Standards, dem Standard-Dateisystemlayout und diversen anderen Dingen. 8 System management commands Dazu gehoren Befehle wie mount(8). Viele davon konnen nur mit Administratorrechten ausgefuhrt werden. Makropaket Neue Handbuchseiten sollten das in man(7) beschriebene Paket an.tmac von groff verwenden. Diese Wahl dient vor allem der Konsistenz: die uberwiegende Mehrheit der existierenden Linux-Handbuchseiten wird mit diesen Makros formatiert. Konventionen fur die Gestaltung der Quelltexte Bitte beschranken Sie die Zeilenlange im Quelltext, wo immer moglich, auf nicht mehr als etwa 75 Zeichen. So werden Zeilenumbruche 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 Grossbuchstaben (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 Anderung, die an der Handbuchseite vorgenommen wurde. (Innerhalb des Projekts man-pages werden die notwendigen Aktualisierungen dieser Zeitstempel automatisch durch Skripte erledigt, daher ist eine handische 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 zwangslaufig das Paket sein muss, welches die Funktionalitat bereitstellt). Handbuchabschnitt Normalerweise sollte dies leer sein, da der Standardwert eine gute Wahl ist. Abschnitte innerhalb einer Handbuchseite Die folgende Liste enthalt gebrauchliche 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] RUCKGABEWERT [in der Regel nur in den Abschnitten 2 und 3] FEHLER [typischerweise nur in den Abschnitten 2 und 3] UMGEBUNGSVARIABLEN DATEIEN ATTRIBUTE [in der Regel nur in den Abschnitten 2 und 3] VERSIONEN [in der Regel nur in den Abschnitten 2 und 3] STANDARDS GESCHICHTE ANMERKUNGEN WARNUNGEN 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 Uberschrift, wo sie zutreffen wurde; diese Art von Konsistenz kann die Informationen leichter verstandlich machen. Wenn Sie mussen, konnen Sie eigene Uberschriften wahlen, wenn die Dinge dadurch leichter zu verstehen sind. (Das kann besonders fur Seiten in den Abschnitten 4 und 5 nutzlich sein.) Doch bevor Sie das tun, prufen Sie bitte, ob Sie auch traditionelle Uberschriften verwenden konnen (und innerhalb dieser Abschnitte einige Unterabschnitte (.SS) einfugen). Die folgende Liste geht naher auf den Inhalt jedes der oben genannten Abschnitte ein. NAME Der Name dieser Handbuchseiten Lesen Sie man(7) fur wichtige Hinweise zu der/den Zeile(n), die dem Befehl .SH NAME folgen sollten. Alle Worter in dieser Zeile (darunter auch das Wort, das unmittelbar auf das >>\-<< folgt) sollten kleingeschrieben werden, ausser 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 Fur Befehle beschreibt dieser Abschnitt die Syntax des Befehls und seine Argumente (einschliesslich 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 auszuwahlen ist, und Ellipsen () konnen wiederholt werden. Fur Funktionen enthalt 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 fur ein Gerat 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 fur das Verstandnis der Schnittstelle sind. Beschreiben Sie den ublichen Fall, fur Informationen uber Befehlszeilenoptionen eines Programms verwenden Sie den Abschnitt OPTIONS. Achten Sie darauf, bei der Beschreibung eines neuen Verhaltens oder eines neuen Schalters fur einen Systemaufruf oder eine Bibliotheksfunktion die Kernel- oder C-Bibliotheksversion anzugeben, bei der diese Anderung eingefuhrt wurde. Die bevorzugte Methode, auf diese Information hinzuweisen, ist bei Schaltern als Teil einer .TP-Liste, in der folgenden Form (hier fur einen neuen Schalter eines Systemaufrufes): XYZ_FLAG (seit Linux 3.7) Beschreibung des Schalters Die Versionsinformation anzugeben ist besonders hilfreich fur Benutzer, die auf eine altere 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 verandern. Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein. EXIT STATUS Eine Liste der moglichen Werte fur den Exit-Status eines Programms und die Umstande, die zur Ruckgabe dieser Werte fuhren Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein. RETURN VALUE Dieser Abschnitt enthalt fur Handbuchseiten aus den Abschnitten 2 und 3 die Ruckgabewerte der Bibliotheksroutine fur die aufrufende Routine und erlautert die Bedingungen, die zu einem bestimmten Ruckgabewert fuhren. ERRORS Dieser Abschnitt enthalt fur Handbuchseiten aus den Abschnitten 2 und 3 mogliche Werte, die im Fehlerfall in errno platziert werden und erlautert mogliche Ursachen der Fehler. Wenn mehrere unterschiedliche Umstande den gleichen Fehler erzeugen, wird bevorzugt, dass verschiedene Listeneintrage (mit gedoppelten Fehlernamen) fur jeden dieser Umstande erstellt werden. Dadurch werden die unterschiedlichen Umstande deutlicher, die Liste einfacher zu lesen und dies erlaubt es, Metainformationen (z.B. Kernelversionsnummern, unter denen die Umstande erstmals zum Tragen kamen) leichter fur jeden Umstand zu markieren. Die Fehlerliste sollte alphabetisch sortiert sein. ENVIRONMENT Eine Liste aller Umgebungsvariablen, die auf das Programm einwirken mit Erlauterung, 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 vollstandigen Pfadnamen dieser Dateien an und nutzen Sie den Installationsprozess, um den Verzeichnisteil des Pfades an die Benutzereinstellungen anzupassen. Fur 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) fur weitere Details. VERSIONS Eine Zusammenfassung der Systeme, auf denen die API direkt funktioniert oder wo es eine ahnliche API gibt. STANDARDS Eine Beschreibung aller Standards oder Konventionen, die die Funktionen oder den Befehle betrifft, die durch die Handbuchseite beschrieben wird. Die bevorzugten Ausdrucke fur die verschiedenen Standards sind als Uberschriften in standards(7) aufgefuhrt. Dieser Abschnitt sollte die aktuellen Standards auflisten, zu denen die API konform ist. Wenn die API von keinen Standards geregelt ist, aber allgemein auf anderen Systemen vorhanden ist, erwahnen Sie diese Systeme. Wenn der Aufruf Linux- oder GNU-spezifisch ist, erwahnen Sie auch das, ausserdem, wenn er in den BSDs verfugbar ist. Wenn dieser Abschnitt nur aus einer Liste von Standards besteht (das ist ublicherweise der Fall), beenden Sie die Liste mit einem Punkt (>>.<<). HISTORY Hier steht eine kurze Zusammenfassung der Linux-Kernel- oder Glibc-Versionen, in denen ein Systemaufruf oder eine Bibliotheksfunktion erschien oder das Verhalten wesentlich veranderte. Als allgemeine Regel gilt, dass jede neue Schnittstelle einen HISTORY-Abschnitt in der Handbuchseite enthalten sollte. Leider verfugen viele bestehende Handbuchseiten nicht uber diese Informationen (da es dafur keine entsprechende Richtlinie gab, als sie geschrieben wurden). Patches zur Erganzung dieser Abschnitte sind willkommen. Aus der Sicht von Programmierern, die neuen Code schreiben, werden diese Informationen wohl nur fur Kernel-Schnittstellen interessant sein, die in Linux 2.4 oder spater hinzugefugt wurden, und fur geanderte Bibliotheksfunktionen in der Glibc seit Version 2.1. (d. h. also Anderungen seit Linux 2.2 und Glibc 2.0). Auch die Handbuchseite uber Systemaufrufe (syscalls(2)) enthalt Informationen uber die Kernel-Versionen, in denen bestimmte Systemaufrufe erstmals vorkamen. Alte Versionen der Standards sollten hier anstatt in STANDARDS erwahnt werden, zum Beispiel SUS, SUSv2 und XPG, oder die SVr4- und 4.xBSD-Implementierungsstandards. NOTES Verschiedene Anmerkungen Fur Handbuchseiten der Abschnitte 2 und 3 konnten die Aufnahme von Unterabschnitten (SS) Linux Notes und Glibc Notes nutzlich sein. In Abschnitt 2 verwenden Sie die Uberschrift C library/kernel differences, um Abschnitte zu markieren, die die Unterschiede (falls vorhanden) zwischen der C-Bibliothek-Wrapper-Funktion fur einen Systemaufruf und der rohen Systemaufrufschnittstelle durch den Kernel beschreiben. CAVEATS Warnungen fur typische fehlerhafte Anwendungen einer API, die jedoch keinen API-Fehler oder Designfehler hervorrufen. BUGS Eine Liste von Einschrankungen, bekannten Mangeln oder Unannehmlichkeiten und weiteren fragwurdigen Verhalten. EXAMPLES Ein oder mehrere Beispiele fur 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 verandern, fugen Sie einen Copyright-Vermerk als Kommentar in die Quelldatei ein. Wenn Sie der Autor eines Geratetreibers sind und eine Adresse fur 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. Schliessen Sie die Liste nicht mit einem Punkt ab. Wenn die >>SEE ALSO<<-Liste viele lange Namen von Handbuchseiten enthalt, 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 konnen Sie vermeiden, indem Sie den Wortern die Zeichenkette >>\%<< voranstellen. Aufgrund der autonomen und verteilten Natur von FOSS-Projekten und ihrer Dokumentation ist es manchmal notwendig - und in vielen Fallen wunschenswert -, dass der Abschnitt >>SIEHE AUCH<< Referenzen auf Handbuchseiten von anderen Projekten enthalt. KONVENTIONEN ZU WORTWAHL UND FORMATIERUNG In den folgenden Unterabschnitten finden Sie einige Details fur die bevorzugten Formatierungs- und Wortwahlkonventionen in den verschiedenen Abschnitten der Seiten im man-pages-Projekt. UBERSICHT Brechen Sie Funktionsprototypen in einem .nf/.fi-Paar um, damit Auffullung vermieden wird. Im Allgemeinen sollten Sie immer, wenn im Abschnitt SYNOPSIS mehrere Funktionsprototypen aufgefuhrt sind, diese nicht durch Leerzeilen trennen. Jedoch durfen Leerzeilen (mit .P) in folgenden Fallen hinzugefugt werden: o um lange Listen von Funktionsprototypen in logische Gruppen zu unterteilen (ein Beispiel finden Sie in list(3)); o in anderen Fallen, wo dies die Lesbarkeit verbessert. Im Abschnitt SYNOPSIS darf ein langer Funktionsprototyp in der nachsten 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 spater bei der Darstellung in einer dicktengleichen Schrift (zum Beispiel in einem xterm) die Fortsetzungszeile direkt unter dem Anfang der Argumentliste eine Zeile daruber beginnt. Eine Ausnahme ware, 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); RUCKGABEWERT Die bevorzugte Formulierung fur das Setzen von errno ist >>errno is set to indicate the error<< oder ahnlich. Diese Formulierung ist zu denen in POSIX.1 und FreeBSD konsistent. ATTRIBUTE Beachten Sie Folgendes: o Brechen Sie die Tabelle in diesem Abschnitt in ein .ad l/.ad-Paar um, um Textauffullung zu vermeiden, und ein .nh/.hy-Paar, um die Silbentrennung zu verhindern. o Stellen Sie sicher, dass die Tabelle die gesamte Seitenbreite einnimmt, indem Sie eine lbx-Beschreibung fur eine der Spalten verwenden (normalerweise die erste Spalte, in einigen Fallen jedoch die letzte Spalte, falls sie viel Text enthalt). o Verwenden Sie so viele T{/T}-Makro-Paare wie moglich, um damit Zeilen in den Tabellenzellen umzubrechen. Denken Sie auch daran, dass Seiten gelegentlich mit weniger als 80 Zeichen Breite dargestellt werden. Beispiele fur alles vorstehend Aufgefuhrte finden Sie im Quelltext diverser Seiten. STIL-RICHTLINIEN Die folgenden Unterabschnitte beschreiben den bevorzugten Stil fur das Projekt man-pages. Im Folgenden nicht erwahnte Details finden Sie moglicherweise im Chicago Manual of Style. Versuchen sie auch, im Verzeichnisbaum des Projekts nach bereits vorhandenen Beispielen bestimmter Anwendungsfalle zu suchen. Geschlechtsneutrale Begriffswahl Verwenden Sie, soweit moglich, eine geschlechtsneutrale Schreibweise in den Texten Ihrer Handbuchseiten. Die Verwendung von >>they<< (>>them<<, >>themself<<, >>their<<) als geschlechtsneutrales Pronomen fur den Singular ist akzeptabel. Konventionen fur 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 fur 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 wurden 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 fur die Auswertung von Handbuch-Quelltexten. Semantische Zeilenvorschube verwenden Im Quelltext einer Handbuchseite sollten neue Satze in einer neuen Zeile beginnen und lange Satze 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 Zeilenvorschube) genannt, erleichtert es, die Wirkung von Patches zu beurteilen, welche oft auf Ebene einzelner Satze, Satzteile oder Phrasen arbeiten. Listen Es gibt verschiedene Arten von Listen: Markierte Absatze Diese werden fur 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 Absatze<<-Unterabschnitt selbst. Geordnete Listen Den Elementen wird eine Zahl in Klammern vorangestellt (>>(1)<<, >>(2)<< ). Diese reprasentieren 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 reprasentieren Felder in einer Menge. Der erste Index wird Folgendes sein: 0 wenn es Felder in einer C-Datenstruktur reprasentiert, um Konsistenz mit Arrays zu gewahrleisten. 1 wenn es Felder in einer Datei reprasentiert, um Konsistenz mit Werkzeugen wie cut(1) zu gewahrleisten. Auswahllisten Den Elementen wird ein Buchstabe in Klammern vorangestellt (>>(a)<<, >>(b)<< ). Diese reprasentieren eine Reihe von sich (normalerweise) gegenseitig ausschliessenden Alternativen. Aufzahlungslisten Den Elementen wird ein Aufzahlungszeichen vorangestellt (\[bu]). Alles, was sich nicht anderweitig kategorisieren lasst, 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 Absatze<<, welche den vorgegebenen Regeln fur die Einruckung folgen. Formatierungskonventionen (Allgemeines) Absatze sollten mit geeigneten Markierungen voneinander getrennt werden (ublicherweise entweder .P oder .IP). Trennen Sie Absatze nicht durch Einfugen 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. ), ausser in der SYNOPSIS, wo eingefugte Dateien fett geschrieben werden (z. B. #include ). Wenn Sie auf die Einbindung einer Standard-Header-Datei verweisen, setzen Sie die Header-Datei wie in C gebrauchlich in spitze Klammern (z.B. ). Spezielle Makros, die in der Regel mit Grossbuchstaben geschrieben werden, werden in Fettdruck gesetzt (z.B. MAXINT). Ausnahme: Schreiben Sie NULL nicht fett. Bei der Aufzahlung einer Liste von Fehlercodes werden die Codes in Fettschrift geschrieben. (Diese Liste verwendet in der Regel das Makro .TP.) Vollstandige Befehle sollten, wenn sie lang sind, eine eigene, eingeruckte Zeile bekommen, der eine Leerzeile vor- und nachgestellt wird, zum Beispiel: man 7 man-pages Kurze Befehle konnen, 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 geschutzte Leerzeichen (\~) zu verwenden. Befehlsoptionen sollten kursiv geschrieben werden (z. B. -l). Ausdrucke sollten kursiv gesetzt werden, wenn Sie nicht auf einer separaten Zeile eingeruckt geschrieben werden. Auch hier kann die Verwendung von geschutzten Leerzeichen angezeigt sein, wenn der Ausdruck in den Fliesstext 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 ermoglicht es Werkzeugen wie man2html(1), korrekte Hyperlinks zu erstellen.) Steuerzeichen sollten in Fettschrift ohne Anfuhrungszeichen geschrieben werden, beispielsweise ^X. Rechtschreibung Seit Release 2.39 folgen die man-pages der amerikanischen Rechtschreibung (vorher bestanden sie aus einer zufalligen 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: o Amerikanisches Englisch tendiert zu den Formen >>backward<<, >>upward<<, >>toward<< und so weiter, wahrend im britischen Englisch eher >>backwards<<, >>upwards<<, >>towards<<, und so weiter verwendet werden. o 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. Grossschreibung In den Uberschriften der Unterabschnitte (>>SS<<) schreiben Sie das erste Wort gross, die anderen Worter 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 eingefugt werden, rucken Sie diese um 4 Leerzeichen ein (d. h. umschliessen Sie den Block mit .in +4n und .in), formatieren Sie sie mittels der Makros .EX und .EE und schliessen Sie sie mit geeigneten Absatzmarkierungen (entweder .P oder .IP) ein. Beispiel: .P .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .P Bevorzugte Begriffe Die folgende Tabelle fuhrt einige bevorzugte Begriffe auf, die in Handbuchseiten verwendet werden sollten, hauptsachlich um Konsistenz innerhalb der Sammlung der Handbuchseiten sicherzustellen. Begriff Nicht verwenden Hinweise ----------------------------------------------------------------- - bit mask bitmask built-in builtin Epoch epoch Fur 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 Ausser beim Verweis auf das Ergebnis von >>uname -m<< oder ahnlichem zeros zeroes Siehe auch den nachfolgenden Abschnitt Bindestriche in attributiven Zusammensetzungen. Zu vermeidende Ausdrucke Die folgende Tabelle fuhrt einige Ausdrucke (zusammen mit Alternativen) auf, die in Handbuchseiten vermieden werden sollten, hauptsachlich um Konsistenz innerhalb der Sammlung der Handbuchseiten sicherzustellen. Vermeiden Stattdessen Hinweise ----------------------------------------------------------- 32bit 32-bit ebenfalls fur 8-bit, 16-bit usw. current process calling process Ein haufiger 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 Geschutzte Marken Verwenden Sie die korrekte Schreibweise fur geschutzte 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<< ausgedruckt wird. Der bevorzugte Begriff fur den Zeiger ist >>null pointer<< oder einfach >>NULL<<, bitte schreiben Sie nicht >>NULL pointer<<. Der bevorzugte Begriff fur 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 konnen als >>null-terminated<< bezeichnet werden, vermeiden Sie dagegen >>NUL-terminated<<. Hyperlinks Verwenden Sie fur Hyperlinks das Makropaar .UR/.UE (siehe groff_man(7)). Dieses erzeugt intakte Hyperlinks, die in einem Webbrowser geoffnet werden konnen, wenn die Seite etwa folgendermassen dargestellt wird: BROWSER=firefox man -H Seitenname Verwendung von e.g., i.e., etc., a.k.a. und ahnlichem Im Allgemeinen sollten Abkurzungen wie >>e.g.<<, >>i.e.<<, >>etc.<<, >>cf.<< und >>a.k.a.<< vermieden werden. Schreiben Sie die Worter stattdessen aus: >>for example<<, >>that is<<, >>and so on<<, >>compare to<<, >>also known as<<. Die einzige Stelle, wo solche Abkurzungen akzeptabel sind, ist in kurzen in Klammern gesetzten Anmerkungen (z.B. wie in dieser hier). Verwenden Sie stets Punkte in solchen Abkurzungen, wie hier gezeigt. Zusatzlich 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 ublicherweise 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 naher 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 Prafixen wie >>multi<<, >>non<<, >>pre<<, >>re<< oder >>sub<< keinen Bindestrich zu setzen. Die Handbuchseiten sollten generell dieser Regel folgen, wenn diese Prafixe 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 Prafixe in Wortern verwendet werden, die nicht zum englischen Standardwortschatz gehoren, wie geschutzte 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 durfte vermutlich jenes sein, was Sie benotigen. Erzeugen optimaler Glyphen Wo ein echtes Minus-Zeichen benotigt wird, zum Beispiel fur die Zahl -1, fur 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 fur Code-Beispiele. Die Verwendung des echten Minuszeichens erfullt die folgenden Zwecke: o Verbesserung der Darstellung fur verschiedene Ziele. Dies gilt insbesondere fur die PDF-Ausgabe und Terminals, die Unicode/UTF-8 darstellen konnen, allerdings nicht fur reine ASCII-Terminals. o Erzeugen von Glyphen, die beim Kopieren von dargestellten Seiten beim Einfugen in ein Terminal echte Minuszeichen erzeugen. Um einfache Anfuhrungszeichen zu verwenden, die in ASCII, in UTF-8 und in PDF korrekt dargestellt werden konnen, 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 (^) benotigt 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 fuhrt 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 konnen Beispielprogramme enthalten, die den Gebrauch von Systemaufrufen oder Bibliotheksfunktionen beschreiben. Beachten Sie jedoch das Folgende: o Beispielprogramme sollten in C geschrieben sein. o 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. o Beispielprogramme sollten idealerweise kurz sein (zum Beispiel konnen bereits weniger als 100 Codezeilen ein gutes Beispiel darstellen), doch konnen in einigen Fallen langere Programme notig sein, um die Verwendung einer API korrekt zu veranschaulichen. o Ausdrucksstarker Code ist sehr begrussenswert. o Kommentare sollten dort eingefugt werden, wo sie hilfreich sind. Vollstandige Satze in freistehenden Kommentaren sollten durch einen Punkt abgeschlossen werden. Kein abschliessender Punkt sollte nach >>tag<<-Kommentaren gesetzt werden (zum Beispiel Kommentare in einer Code-Zeile), da solche Kommentare eher kurze Phrasen und keine kompletten Satze sind. o Beispielprogramme sollten nach dem Aufruf von System- und Bibliotheksfunktionen prufen, ob Fehler aufgetreten sind. o Beispielprogramme sollten vollstandig sein und keine Warnungen ausgeben, wenn sie mit cc -Wall kompiliert werden. o Soweit moglich und angebracht, sollten Beispielprogramme Experimente ermoglichen, wie sich ihr Verhalten durch Variation der Eingabe verandert (idealerweise mittels Befehlszeilenargumenten oder alternativ durch vom Programm gelesene Eingaben). o Beispielprogramme sollten im Stil von Kernighan und Ritchie (mit Einzugen von 4 Leerzeichen) verfasst werden. (Verwenden Sie in Quelltexten keine Tabulatoren!) Der folgende Befehl kann dazu verwandt werden, Ihren Quellcode ahnlich dem bevorzugten Stil zu formatieren: indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c o Aus Konsistenzgrunden 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; o Falls ein umfangreicher erklarender Text vor dem Programm-Quellcode steht, markieren Sie den Quellcode mit der Zwischenuberschrift Program source, wie in: .SS Program source Tun Sie dies immer, wenn der erklarende Text ein Sitzungsprotokoll der Shell enthalt. Wenn Sie eine Shell-Sitzung einfugen, welche die Verwendung eines Programms oder andere Moglichkeiten des Systems demonstriert: o Setzen Sie das Sitzungsprotokoll vor die Quellcode-Auflistung. o Rucken Sie das Sitzungsprotokoll um vier Zeichen ein. o Wahlen Sie Fettschrift fur 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 fur die Gestaltung von Handbuchseiten fur 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) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer , Mario Blattermann , Stephan Beck , Dr. Tobias Quathamer und Helge Kreutzmann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.06 31. Oktober 2023 man-pages(7)