Provided by: manpages-de_4.21.0-2_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
              VERSIONEN            [in der Regel nur in den Abschnitten 2 und 3]
              ATTRIBUTE            [in der Regel nur in den Abschnitten 2 und 3]
              STANDARDS
              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
              Hier steht eine kurze Zusammenfassung der Linux-Kernel-  oder  Glibc-Versionen,  in
              denen  ein  Systemaufruf  oder eine Bibliotheksfunktion erschien oder das Verhalten
              wesentlich veränderte.

              Als allgemeine Regel gilt, dass jede neue Schnittstelle einen VERSIONS-Abschnitt in
              der Handbuchseite enthalten sollte. Leider verfügen viele bestehende Handbuchseiten
              nicht über diese Informationen (da es dafür keine entsprechende Richtlinie gab, als
              sie  geschrieben  wurden). Patches zur Ergänzung dieser Abschnitte sind willkommen.
              Aus  der  Sicht  von  Programmierern,  die  neuen  Code  schreiben,  werden   diese
              Informationen wohl nur für Kernel-Schnittstellen interessant sein, die in Linux 2.4
              oder später hinzugefügt wurden, und  für  geänderte  Bibliotheksfunktionen  in  der
              Glibc seit Version 2.1. (d. h. also Änderungen seit Linux 2.2 und Glibc 2.0).

              Auch  die Handbuchseite über Systemaufrufe (syscalls(2)) enthält Informationen über
              die Kernel-Versionen, in denen bestimmte Systemaufrufe erstmals vorkamen.

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

              Die bevorzugten Ausdrücke für die verschiedenen Standards sind als Überschriften in
              standards(7) aufgeführt.

              Für eine Handbuchseite in Abschnitt 2 oder 3 sollte(n) hier die POSIX.1-Version(en)
              stehen, denen der Aufruf entspricht. Auch sollte angegeben werden, ob der Aufruf in
              C99 beschrieben ist. (Sorgen Sie sich nicht zu sehr um andere  Standards  wie  SUS,
              SUSv2 und XPG oder die SVr4- und 4.xBSD-Implementierungsstandards, es sei denn, der
              Aufruf wurde in diesen Standards beschrieben,  ist  aber  nicht  in  der  aktuellen
              Version von POSIX.1 enthalten.)

              Wenn  der  Aufruf  von  keinen  Standards  geregelt ist, aber allgemein auf anderen
              Systemen  vorhanden  ist,   erwähnen   Sie   diese   Systeme.   Wenn   der   Aufruf
              Linux-spezifisch ist, erwähnen Sie auch das.

              Wenn  dieser  Abschnitt  nur  aus  einer  Liste  von  Standards  besteht  (das  ist
              üblicherweise der Fall), beenden Sie die Liste mit einem Punkt (».«).

       NOTES  Verschiedene Anmerkungen

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

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

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

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

       EXAMPLES
              Ein oder mehrere Beispiele für die Anwendung  der  Funktion,  der  Datei  oder  des
              Befehls

              Wie   Beispielprogramme   geschrieben  werden  sollten,  beschreibt  der  Abschnitt
              Beispielprogramme weiter unten.

       AUTHORS
              Eine Liste der Autoren der Dokumentation oder des Programms

              Von einem AUTHORS-Bereich wird entschieden  abgeraten.  Allgemein  ist  es  besser,
              nicht  jede  Seite  mit  einer Liste von (im Laufe der Zeit potenziell zahlreichen)
              Autoren vollzustopfen. Wenn Sie eine Seite schreiben  oder  signifikant  verändern,
              fügen Sie einen Copyright-Vermerk als Kommentar in die Quelldatei ein. Wenn Sie der
              Autor eines Gerätetreibers sind und eine Adresse für das Melden von Fehlern angeben
              wollen, tun Sie das im Abschnitt FEHLER.

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

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

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

              Die  Liste  sollte  nach  Abschnittsnummern  und  in  den  Abschnitten alphabetisch
              sortiert werden. Schließen Sie die Liste nicht mit einem Punkt ab.

              Wenn die »SEE ALSO«-Liste viele lange Namen von Handbuchseiten enthält, kann es zur
              Verbesserung  der visuellen Darstellung sinnvoll sein, die Anweisungen .ad l (nicht
              rechts anordnen) und .nh (keine Silbentrennung) zu  verwenden.  Die  Silbentrennung
              individueller   Seitennamen  können  Sie  vermeiden,  indem  Sie  den  Wörtern  die
              Zeichenkette »\%« voranstellen.

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

KONVENTIONEN ZU WORTWAHL UND FORMATIERUNG

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

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

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

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

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

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

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

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

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

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

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

   ATTRIBUTE
       Beachten Sie Folgendes:

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

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

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

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

STIL-RICHTLINIEN

       Die folgenden Unterabschnitte beschreiben den bevorzugten Stil für das Projekt  man-pages.
       Im  Folgenden nicht erwähnte Details finden Sie möglicherweise im Chicago Manual of Style.
       Versuchen sie auch, im Verzeichnisbaum des Projekts nach  bereits  vorhandenen  Beispielen
       bestimmter Anwendungsfälle zu suchen.

   Geschlechtsneutrale Begriffswahl
       Verwenden  Sie,  soweit möglich, eine geschlechtsneutrale Schreibweise in den Texten Ihrer
       Handbuchseiten.  Die   Verwendung   von   »they«   (»them«,   »themself«,   »their«)   als
       geschlechtsneutrales Pronomen für den Singular ist akzeptabel.

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

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

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

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

       Variablennamen sollten wie die Namen von Argumenten kursiv geschrieben werden.

       Jeder Hinweis auf den Gegenstand der aktuellen Handbuchseite sollte mit  diesem  Namen  in
       Fettschrift  geschrieben werden, gefolgt von einem Paar Klammern in Normalschrift (Roman).
       Zum Beispiel würden in der Handbuchseite von fcntl(2) Verweise auf das Thema der Seite als
       fcntl() geschrieben werden. Die empfohlene Schreibweise in der Quelldatei ist

           .BR fcntl ().

       Die  Verwendung  dieses  Formats  anstatt  »\fB…\fP()«  erleichtert  die  Entwicklung  von
       Werkzeugen für die Auswertung von Handbuch-Quelltexten.

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

   Listen
       Es gibt verschiedene Arten von Listen:

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

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

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

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

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

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

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

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

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

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

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

       Dateinamen (ob Pfadnamen oder Verweise auf Header-Dateien) werden immer kursiv gesetzt (z.
       B. <stdio.h>), außer in der SYNOPSIS, wo eingefügte Dateien fett geschrieben werden (z. B.
       #include  <stdio.h>).  Wenn  Sie auf die Einbindung einer Standard-Header-Datei verweisen,
       setzen Sie die Header-Datei wie in C gebräuchlich in spitze Klammern (z.B. <stdio.h>).

       Spezielle Makros, die in der  Regel  mit  Großbuchstaben  geschrieben  werden,  werden  in
       Fettdruck gesetzt (z.B. MAXINT). Ausnahme: Schreiben Sie NULL nicht fett.

       Bei   der  Aufzählung  einer  Liste  von  Fehlercodes  werden  die  Codes  in  Fettschrift
       geschrieben. (Diese Liste verwendet in der Regel das Makro .TP.)

       Vollständige Befehle sollten, wenn sie lang sind, eine eigene, eingerückte Zeile bekommen,
       der eine Leerzeile vor- und nachgestellt wird, zum Beispiel:

           man 7 man-pages

       Kurze  Befehle können, kursiv gesetzt, in den laufenden Text aufgenommen werden; z. B. man
       7 man-pages. In diesem Fall kann es sich lohnen, an geeigneten Stellen in der Befehlszeile
       geschützte  Leerzeichen  (\~)  zu  verwenden.  Befehlsoptionen  sollten kursiv geschrieben
       werden (z. B. -l).

       Ausdrücke sollten kursiv  gesetzt  werden,  wenn  Sie  nicht  auf  einer  separaten  Zeile
       eingerückt  geschrieben  werden. Auch hier kann die Verwendung von geschützten Leerzeichen
       angezeigt sein, wenn der Ausdruck in den Fließtext integriert ist.

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

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

       Jeder Verweis auf eine andere Handbuchseite sollte den Namen in Fettschrift darstellen und
       immer ohne Leerzeichen von der Nummer des  Abschnitts  in  Normalschrift  (Roman)  gefolgt
       werden; (z. B. intro(2)). Die empfohlene Schreibweise in der Quelldatei ist

           .BR intro (2).

       (Die   Angabe   der   Abschnittsnummer  in  Querverweisen  ermöglicht  es  Werkzeugen  wie
       man2html(1), korrekte Hyperlinks zu erstellen.)

       Steuerzeichen  sollten  in  Fettschrift   ohne   Anführungszeichen   geschrieben   werden,
       beispielsweise ^X.

   Rechtschreibung
       Seit  Release  2.39  folgen  die  man-pages  der  amerikanischen  Rechtschreibung  (vorher
       bestanden  sie  aus  einer  zufälligen  Mischung   aus   britischer   und   amerikanischer
       Rechtschreibung).   Bitte  verfassen  Sie  alle  neuen  Seiten  und  Patches  nach  diesen
       Konventionen.

       Abgesehen von den  gut  bekannten  Rechtschreibunterschieden  gibt  es  ein  paar  weitere
       Feinheiten, auf die Sie achten sollten:

       •  Amerikanisches  Englisch  tendiert  zu den Formen »backward«, »upward«, »toward« und so
          weiter, während im britischen Englisch eher »backwards«, »upwards«, »towards«,  und  so
          weiter verwendet werden.

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

   BSD-Versionsnummern
       Das klassische Schema zum Schreiben von BSD-Versionsnummern lautet x.yBSD, wobei  x.y  die
       Versionsnummer ist (z.B. 4.2BSD). Vermeiden Sie Formen der Art BSD 4.3.

   Großschreibung
       In  den  Überschriften  der  Unterabschnitte (»SS«) schreiben Sie das erste Wort groß, die
       anderen Wörter dagegen nicht, es sei denn, die Konventionen der  englischen  Sprache  (zum
       Beispiel   Eigennamen)   oder   Erfordernisse   der   Programmiersprache   (zum   Beispiel
       Identifizierernamen) erzwingen die Abweichung von dieser Regel. Beispiel:

           .SS Unicode under Linux

   Einzug bei Strukturdefinitionen, Protokollen von Shell-Sitzungen und so weiter.
       Wenn  Struktur-Definitionen,  Protokolle  von  Shell-Sitzungen  usw.  im  laufenden   Text
       eingefügt  werden,  rücken Sie diese um 4 Leerzeichen ein (d. h. umschließen Sie den Block
       mit .in +4n und .in), formatieren Sie sie mittels der Makros .EX und .EE und schließen Sie
       sie mit geeigneten Absatzmarkierungen (entweder .PP oder .IP) ein. Beispiel:

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

   Bevorzugte Begriffe
       Die folgende Tabelle führt einige bevorzugte Begriffe auf, die in Handbuchseiten verwendet
       werden sollten, hauptsächlich um Konsistenz  innerhalb  der  Sammlung  der  Handbuchseiten
       sicherzustellen.

       Begriff              Nicht verwenden          Hinweise
       ───────────────────────────────────────────────────────────────────
       bit mask             bitmask
       built-in             builtin
       Epoch                epoch                    Für den Beginn der
                                                     UNIX-Zeitrechnung
                                                     (00:00:00, 1.
                                                     Januar 1970 UTC)
       Dateiname            file name
       Dateisystem          file system
       Rechnername          host name
       inode                i-node
       lowercase            lower case, lower-case
       nonzero              non-zero
       pathname             path name
       pseudoterminal       pseudo-terminal
       privileged port      reserved port, system
                            port
       real-time            realtime, real time
       run time             runtime
       saved set-group-ID   saved group ID, saved
                            set-GID

       saved set-user-ID    saved user ID, saved
                            set-UID
       set-group-ID         set-GID, setgid
       set-user-ID          set-UID, setuid
       superuser            super user, super-user
       superblock           super block,
                            super-block
       symbolic link        symlink
       timestamp            time stamp
       timezone             time zone
       uppercase            upper case, upper-case
       usable               useable
       user space           userspace
       username             user name
       x86-64               x86_64                   Außer beim Verweis
                                                     auf das Ergebnis
                                                     von »uname -m« oder
                                                     ähnlichem
       zeros                zeroes

       Siehe auch den nachfolgenden Abschnitt Bindestriche in attributiven Zusammensetzungen.

   Zu vermeidende Ausdrücke
       Die folgende Tabelle führt einige Ausdrücke (zusammen mit Alternativen) auf, die in
       Handbuchseiten vermieden werden sollten, hauptsächlich um Konsistenz innerhalb der
       Sammlung der Handbuchseiten sicherzustellen.

       Vermeiden         Stattdessen             Hinweise
       ──────────────────────────────────────────────────────────────────

       32bit             32-bit                  ebenfalls für 8-bit,
                                                 16-bit usw.
       current process   calling process         Ein häufiger Fehler der
                                                 Kernel-Programmierer
                                                 beim Schreiben von
                                                 Handbuchseiten
       manpage           man page, manual page
       minus infinity    negative infinity
       non-root          unprivileged user
       non-superuser     unprivileged user
       nonprivileged     unprivileged
       OS                operating system
       plus infinity     positive infinity
       pty               pseudoterminal
       tty               terminal
       Unices            UNIX systems
       Unixes            UNIX systems

   Geschützte Marken
       Verwenden Sie die korrekte Schreibweise für geschützte Marken. Nachfolgend finden Sie eine
       Liste der korrekten Schreibweisen diverser  relevanter  Marken,  die  gelegentlich  falsch
       geschrieben werden:

              DG/UX
              HP-UX
              UNIX
              UnixWare

   NULL, NUL, Null-Zeiger und Null-Byte
       Ein  null pointer ist ein Zeiger, der auf nichts verweist. Er wird normalerweise durch die
       Konstante NULL angegeben. Andererseits bezeichnet NUL das NULL-Byte, ein Byte mit dem Wert
       0, das in C durch die Zeichenkonstante »\0« ausgedrückt wird.

       Der  bevorzugte  Begriff  für  den  Zeiger  ist  »null pointer« oder einfach »NULL«, bitte
       schreiben Sie nicht »NULL pointer«.

       Der bevorzugte Begriff für das Byte ist »null byte«. Bitte schreiben Sie nicht  »NUL«,  da
       es  zu  leicht  mit  »NULL« verwechselt werden kann. Vermeiden Sie auch die Begriffe »zero
       byte« und »null character«. Das Byte, das eine C-Zeichenkette  beendet,  sollte  als  »the
       terminating  null  byte«  beschrieben  werden.  Zeichenketten können als »null-terminated«
       bezeichnet werden, vermeiden Sie dagegen »NUL-terminated«.

   Hyperlinks
       Verwenden Sie für Hyperlinks das Makropaar .UR/.UE (siehe  groff_man(7)).  Dieses  erzeugt
       intakte  Hyperlinks,  die  in einem Webbrowser geöffnet werden können, wenn die Seite etwa
       folgendermaßen dargestellt wird:

           BROWSER=firefox man -H Seitenname

   Verwendung von e.g., i.e., etc., a.k.a. und ähnlichem
       Im Allgemeinen  sollten  Abkürzungen  wie  »e.g.«,  »i.e.«,  »etc.«,  »cf.«  und  »a.k.a.«
       vermieden werden. Schreiben Sie die Wörter stattdessen aus: »for example«, »that is«, »and
       so on«, »compare to«, »also known as«.

       Die einzige Stelle, wo solche Abkürzungen akzeptabel  sind,  ist  in  kurzen  in  Klammern
       gesetzten Anmerkungen (z.B. wie in dieser hier).

       Verwenden Sie stets Punkte in solchen Abkürzungen, wie hier gezeigt. Zusätzlich sollte auf
       »e.g.« und »i.e.« stets ein Komma folgen.

   Em-Gedankenstriche
       Einen em-Gedankenstrich – das Zeichen, das an beiden  Enden  dieses  Satzteiles  steht  –,
       setzen   Sie  in  *roff  mit  dem  Makro  »\[em]«.  (Auf  einem  ASCII-Terminal  wird  ein
       em-Gedankenstrich üblicherweise als zwei Bindestriche, in anderen typografischen Kontexten
       als   langer   Gedankenstrich  dargestellt.)  Em-Gedankenstriche  sollten  ohne  vor-  und
       nachstehendes Leerzeichen geschrieben werden.

   Bindestriche in attributiven Zusammensetzungen
       Zusammengesetzte Begriffe  sollten  mit  Bindestrich  geschrieben  werden,  wenn  Sie  als
       Attribut  verwendet  werden,  zum Beispiel, um ein nachfolgendes Nomen näher zu bestimmen.
       Einige Beispiele:

              32-bit value
              command-line argument
              floating-point number
              run-time check
              user-space function
              wide-character string

   Zusammensetzungen mit multi, non, pre, re, sub, usw.
       Die allgemeine Tendenz im modernen Englisch ist es,  nach  Präfixen  wie  »multi«,  »non«,
       »pre«,  »re«  oder »sub« keinen Bindestrich zu setzen. Die Handbuchseiten sollten generell
       dieser Regel folgen, wenn diese Präfixe in nativen englischen  Konstrukten  mit  einfachen
       Suffixen  verwendet  werden.  Die  folgende  Liste  zeigt einige Beispiele der bevorzugten
       Formen:

              interprocess
              multithreaded
              multiprocess
              nonblocking
              nondefault
              nonempty
              noninteractive
              nonnegative
              nonportable
              nonzero
              preallocated
              precreate
              prerecorded
              reestablished
              reinitialize
              rearm
              reread
              subcomponent
              subdirectory
              subsystem

       Bindestriche sollten gesetzt werden, wenn die Präfixe in  Wörtern  verwendet  werden,  die
       nicht  zum  englischen  Standardwortschatz  gehören,  wie  geschützte  Marken, Eigennamen,
       Akronyme oder zusammengesetzte Begriffe. Einige Beispiele:

              non-ASCII
              non-English
              non-NULL
              non-real-time

       Beachten Sie auch, dass »re-create« und »recreate« zwei Verben unterschiedlicher Bedeutung
       sind. Das erstere dürfte vermutlich jenes sein, was Sie benötigen.

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

           \-

       Diese Richtlinie gilt auch für Code-Beispiele.

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

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

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

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

           \[aq]C\[aq]

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

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

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

   Beispielprogramme und Shell-Sitzungen
       Handbuchseiten können Beispielprogramme enthalten, die  den  Gebrauch  von  Systemaufrufen
       oder Bibliotheksfunktionen beschreiben. Beachten Sie jedoch das Folgende:

       •  Beispielprogramme sollten in C geschrieben sein.

       •  Ein  Beispielprogramm  ist  nur  dann notwendig und sinnvoll, wenn es inhaltlich weiter
          geht als das, was leicht in einer  Textbeschreibung  der  Schnittstelle  bereitgestellt
          werden  kann.  Ein  Beispielprogramm,  das  nichts  Anderes tut, als eine Schnittstelle
          aufzurufen, hat in der Regel wenig Sinn.

       •  Beispielprogramme sollten idealerweise kurz sein (zum Beispiel können  bereits  weniger
          als  100  Codezeilen  ein  gutes  Beispiel  darstellen),  doch können in einigen Fällen
          längere Programme nötig sein, um die Verwendung einer API korrekt zu veranschaulichen.

       •  Ausdrucksstarker Code ist sehr begrüßenswert.

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

       •  Beispielprogramme sollten nach dem Aufruf von System- und Bibliotheksfunktionen prüfen,
          ob Fehler aufgetreten sind.

       •  Beispielprogramme  sollten  vollständig sein und keine Warnungen ausgeben, wenn sie mit
          cc -Wall kompiliert werden.

       •  Soweit möglich und angebracht, sollten Beispielprogramme Experimente  ermöglichen,  wie
          sich  ihr  Verhalten  durch  Variation  der  Eingabe  verändert  (idealerweise  mittels
          Befehlszeilenargumenten oder alternativ durch vom Programm gelesene Eingaben).

       •  Beispielprogramme sollten im Stil  von  Kernighan  und  Ritchie  (mit  Einzügen  von  4
          Leerzeichen)  verfasst  werden.  (Verwenden  Sie in Quelltexten keine Tabulatoren!) Der
          folgende Befehl kann dazu verwandt werden, Ihren Quellcode ähnlich dem bevorzugten Stil
          zu formatieren:

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

       •  Aus  Konsistenzgründen  sollten alle Beispielprogramm mit einer der folgenden Sequenzen
          beendet werden:

              exit(EXIT_SUCCESS);
              exit(EXIT_FAILURE);

          Vermeiden Sie die folgenden Formen, um ein Programm zu beenden:

              exit(0);
              exit(1);
              return n;

       •  Falls ein umfangreicher erklärender Text vor dem  Programm-Quellcode  steht,  markieren
          Sie den Quellcode mit der Zwischenüberschrift Program source, wie in:

              .SS Program source

          Tun Sie dies immer, wenn der erklärende Text ein Sitzungsprotokoll der Shell enthält.

       Wenn  Sie  eine  Shell-Sitzung einfügen, welche die Verwendung eines Programms oder andere
       Möglichkeiten des Systems demonstriert:

       •  Setzen Sie das Sitzungsprotokoll vor die Quellcode-Auflistung.

       •  Rücken Sie das Sitzungsprotokoll um vier Zeichen ein.

       •  Wählen Sie Fettschrift für vom Benutzer eingegebenen Text, um ihn von  der  vom  System
          erzeugten Ausgabe zu unterscheiden.

       In wait(2) und pipe(2) finden Sie vorbildliche Beispielprogramme.

BEISPIELE

       Kanonische  Beispiele  für  die Gestaltung von Handbuchseiten für das man-pages-Paket sind
       pipe(2) und fcntl (2).

SIEHE AUCH

       man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)

ÜBERSETZUNG

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

       Diese  Übersetzung  ist  Freie  Dokumentation;  lesen  Sie  die GNU General Public License
       Version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ oder neuer bezüglich der  Copyright-
       Bedingungen. Es wird KEINE HAFTUNG übernommen.

       Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-
       Mail an die Mailingliste der Übersetzer ⟨debian-l10n-german@lists.debian.org⟩.