oracular (7) man-pages.7.gz

Provided by: manpages-de_4.23.1-1_all bug

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
              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 Ü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
              Eine  Zusammenfassung  der Systeme, auf denen die API direkt funktioniert oder wo es eine ähnliche
              API gibt.

       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.

              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,
              erwähnen Sie diese Systeme. Wenn der Aufruf Linux- oder GNU-spezifisch ist, erwähnen Sie auch das,
              außerdem, wenn er in den BSDs verfügbar ist.

              Wenn dieser Abschnitt nur aus einer Liste von Standards besteht (das ist üblicherweise 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 veränderte.

              Als  allgemeine  Regel  gilt,  dass  jede  neue  Schnittstelle  einen  HISTORY-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.

       Alte  Versionen  der  Standards sollten hier anstatt in STANDARDS erwähnt werden, zum Beispiel SUS, SUSv2
       und XPG, oder die SVr4- und 4.xBSD-Implementierungsstandards.

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