.\" -*- coding: UTF-8 -*- .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler .\" (faith@cs.unc.edu and dwheeler@ida.org) .\" and (C) Copyright 2007 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH MAN\-PAGES 7 "13. August 2020" Linux Linux\-Programmierhandbuch .SH BEZEICHNUNG man\-pages \- Konventionen für das Schreiben von Linux\-Handbuchseiten .SH ÜBERSICHT \fBman\fP [\fIAbschnitt\fP] \fITitel\fP .SH BESCHREIBUNG Diese Seite beschreibt die Konventionen, die Sie einhalten sollten, wenn Sie Handbuchseiten für das Projekt »Linux \fIman\-pages\fP« 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. .SS "Gliederung der Handbuchseiten" Die Handbuchseiten sind traditionell in die folgenden Abschnitte eingeteilt: .TP \fB1 User commands (Programs)\fP Befehle, die ein Benutzer in der Shell ausführen kann. .TP \fB2 System calls\fP Funktionen, die vom Kernel ausgeführte Aktionen umhüllen (»wrap«). .TP \fB3 Library calls\fP Alle Bibliotheksfunktionen außer den Systemaufruf\-Wrappern (die meisten der \fIlibc\fP\-Funktionen). .TP \fB4 Special files (devices)\fP Dateien, die in \fI/dev\fP liegen und den Zugriff auf Geräte über den Kernel erlauben. .TP \fB5 File formats and configuration files\fP Beschreibt verschiedene menschenlesbare Dateiformate und Konfigurationsdateien. .TP \fB6 Games\fP Auf dem System verfügbare Spiele und lustige kleine Programme. .TP \fB7 Overview, conventions, and miscellaneous\fP Überblicke oder Beschreibungen verschiedener Themen, Konventionen und Protokolle, Zeichensatz\-Standards, dem Standard\-Dateisystemlayout und diversen anderen Dingen. .TP \fB8 System management commands\fP .\" .TP .\" .B 9 Kernel routines .\" This is an obsolete manual section. .\" Once it was thought a good idea to document the Linux kernel here, .\" but in fact very little has been documented, and the documentation .\" that exists is outdated already. .\" There are better sources of .\" information for kernel developers. Dazu gehören Befehle wie \fBmount\fP(8). Viele davon können nur mit Administratorrechten ausgeführt werden. .SS Makropaket Neue Handbuchseiten sollten das in \fBman\fP(7) beschriebene Paket \fBan.tmac\fP von \fBgroff\fP verwenden. Diese Wahl dient vor allem der Konsistenz: die überwiegende Mehrheit der existierenden Linux\-Handbuchseiten wird mit diesen Makros formatiert. .SS "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. .SS Titelzeile Der erste Befehl einer Handbuchseite sollte ein \fBTH\fP\-Befehl sein: .PP .RS \fB\&.TH\fP \fITitel Abschnitt Datum Quelle Handbuch\fP .RE .PP Die Argumente dieses Befehls sind wie folgt: .TP \fITitel\fP der Titel der Handbuchseite in Großbuchstaben (z. B. \fIMAN\-PAGES\fP) .TP \fIAbschnitt\fP die Nummer des Abschnitts, in dem die Handbuchseite eingeordnet werden sollte (z. B. \fI7\fP) .TP \fIDatum\fP Das Datum der letzten nicht trivialen Änderung, die an der Handbuchseite vorgenommen wurde. (Innerhalb des Projekts \fIman\-pages\fP 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. .TP \fIQuelle\fP die Quelle von Befehl, Funktion oder Systemaufruf .IP Für die wenigen \fIHandbuchseiten\fP in den Abschnitten 1 und 8 werden Sie vielleicht nur \fIGNU\fP schreiben wollen. .IP Für Systemaufrufe schreiben Sie einfach \fILinux\fP. (Eine frühere Praxis war es, die Kernel\-Version anzugeben, für die die Seite geschrieben oder mit der sie überprüft wurde. Dies wurde jedoch nie konsequent durchgeführt und war vielleicht schlimmer als gar keine Versionsnummer. Vermeiden Sie künftig die Versionsnummer.) .IP Für Bibliotheksaufrufe, die Teil der Glibc oder einer der anderen gängigen GNU\-Bibliotheken sind, schreiben Sie einfach \fIGNU C Library\fP, \fIGNU\fP oder eine leere Zeichenkette. .IP Verwenden Sie für Seiten aus Abschnitt 4 \fILinux\fP. .IP Wählen Sie in Zweifelsfällen einfach \fILinux\fP oder \fIGNU\fP. .TP \fIHandbuch\fP .\" der Titel des Handbuchs (z. B. für Seiten der Abschnitte 2 und 3 aus dem Paket \fIman\-pages\fP verwenden Sie bitte \fILinux Programmer's Manual\fP. .SS "Abschnitte innerhalb einer Handbuchseite" Die folgende Liste enthält gebräuchliche und empfohlene Abschnitte. Die meisten Handbuchseiten sollten mindestens die \fBhervorgehobenen\fP Abschnitte enthalten. Gliedern Sie eine neue Handbuchseite so, dass die Abschnitte in der Reihenfolge der Liste platziert werden. .PP .RS .TS l l. \fBNAME\fP \fBSYNOPSIS\fP KONFIGURATION [in der Regel nur in Abschnitt 4] \fBDESCRIPTION\fP 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] .\" May 07: Few current man pages have an ERROR HANDLING section,,, .\" ERROR HANDLING, FEHLER [typischerweise nur in den Abschnitten 2 und 3] .\" May 07: Almost no current man pages have a USAGE section,,, .\" USAGE, .\" DIAGNOSTICS, .\" May 07: Almost no current man pages have a SECURITY section,,, .\" SECURITY, UMGEBUNGSVARIABLEN DATEIEN VERSIONEN [in der Regel nur in den Abschnitten 2 und 3] ATTRIBUTE [in der Regel nur in den Abschnitten 2 und 3] KONFORM ZU ANMERKUNGEN FEHLER BEISPIELE .\" AUTHORS sections are discouraged AUTOREN [wird nicht empfohlen] FEHLER MELDEN [wird in man\-pages nicht verwendet] COPYRIGHT [wird in man\-pages nicht verwendet] \fBSEE ALSO\fP .TE .RE .PP \fIBitte verwenden Sie eine traditionelle Überschrift\fP, \fIwo sie zutreffen würde\fP; 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 (\fI.SS\fP) einfügen). .PP Die folgende Liste geht näher auf den Inhalt jedes der oben genannten Abschnitte ein. .TP \fBNAME\fP Der Name dieser Handbuchseiten .IP Lesen Sie \fBman\fP(7) für wichtige Hinweise zu der/den Zeile(n), die dem Befehl \fB.SH NAME\fP folgen sollten. Alle Wörter in dieser Zeile (darunter auch das Wort, das unmittelbar auf das »\e\-« folgt) sollten kleingeschrieben werden, außer wenn das Englische oder die Gepflogenheiten der Fachbegriffe es anders vorschreiben. .TP \fBSYNOPSIS\fP Eine kurze Zusammenfassung des Befehls oder der Funktionsschnittstelle .IP 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 \fB#include\fP\-Anweisungen, gefolgt von der Funktionsdeklaration. .IP .\" FIXME . Say something here about compiler options 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 \fBfeature_test_macros\fP(7) beschrieben. .TP \fBCONFIGURATION\fP Konfigurationsdetails für ein Gerät .IP Dieser Abschnitt kommt in der Regel nur in Seiten aus Abschnitt 4 vor. .TP \fBDESCRIPTION\fP Eine Bescheibung der Funktionsweise des Programms, der Funktion oder des Formats .IP .\" If there is some kind of input grammar or complex set of subcommands, .\" consider describing them in a separate .\" .B USAGE .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). 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 \fBOPTIONS\fP. .IP 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 \fB.TP\fP\-Liste, in der folgenden Form (hier für einen neuen Schalter eines Systemaufrufes): .RS 16 .TP \fBXYZ_FLAG\fP (seit Linux 3.7) Beschreibung des Schalters … .RE .IP 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). .TP \fBOPTIONS\fP Eine Beschreibung der von einem Programm akzeptierten Befehlszeilenoptionen und wie sie das Verhalten des Programms verändern. .IP .\" .TP .\" .B USAGE .\" describes the grammar of any sublanguage this implements. Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein. .TP \fBEXIT STATUS\fP 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 .IP Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein. .TP \fBRETURN VALUE\fP 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. .TP \fBERRORS\fP Dieser Abschnitt enthält für Handbuchseiten aus den Abschnitten 2 und 3 mögliche Werte, die im Fehlerfall in \fIerrno\fP platziert werden und erläutert mögliche Ursachen der Fehler. .IP 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. .IP \fIDie Fehlerliste sollte alphabetisch sortiert sein\fP. .TP \fBENVIRONMENT\fP Eine Liste aller Umgebungsvariablen, die auf das Programm einwirken mit Erläuterung, was sie bewirken. .TP \fBFILES\fP Eine Liste aller Dateien, die das Programm oder die Funktion verwenden, wie Konfigurationsdateien, Einrichtungsdateien und Dateien, auf denen das Programm direkt arbeitet .IP .\" May 07: Almost no current man pages have a DIAGNOSTICS section; .\" "RETURN VALUE" or "EXIT STATUS" is preferred. .\" .TP .\" .B DIAGNOSTICS .\" gives an overview of the most common error messages and how to .\" cope with them. .\" You don't need to explain system error messages .\" or fatal signals that can appear during execution of any program .\" unless they're special in some way to the program. .\" .\" May 07: Almost no current man pages have a SECURITY section. .\".TP .\".B SECURITY .\"discusses security issues and implications. .\"Warn about configurations or environments that should be avoided, .\"commands that may have security implications, and so on, especially .\"if they aren't obvious. .\"Discussing security in a separate section isn't necessary; .\"if it's easier to understand, place security information in the .\"other sections (such as the .\" .B DESCRIPTION .\" or .\" .B USAGE .\" section). .\" However, please include security information somewhere! 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 \fI/usr/local\fP voreingestellt. Ihre grundlegende Handbuchseite sollte daher \fI/usr/local\fP als Basis verwenden. .TP \fBATTRIBUTES\fP Eine Zusammenfassung der verschiedenen Attribute von Funktionen, die auf dieser Seite dokumentiert sind. Siehe \fBattributes\fP(7) für weitere Details. .TP \fBVERSIONS\fP 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. .IP Als allgemeine Regel gilt, dass jede neue Schnittstelle einen VERSIONS\-Abschnitt in der Handbuchseite enthalten sollte. Leider verfügen viele bestehende Handbuchseiten nicht über diese Informationen (da es dafür keine entsprechende Richtlinie gab, als sie geschrieben wurden). Patches zur Ergänzung dieser Abschnitte sind willkommen. Aus der Sicht von Programmierern, die neuen Code schreiben, werden diese Informationen wohl nur für Kernel\-Schnittstellen interessant sein, die in Linux 2.4 oder später hinzugefügt wurden, und für geänderte Bibliotheksfunktionen in der Glibc seit Version 2.1. (d. h. also Änderungen seit Kernel 2.2 und Glibc 2.0). .IP Auch die Handbuchseite über Systemaufrufe (\fBsyscalls\fP(2)) enthält Informationen über die Kernel\-Versionen, in denen bestimmte Systemaufrufe erstmals vorkamen. .TP \fBCONFORMING TO\fP Eine Beschreibung aller Standards oder Konventionen, die die Funktionen oder den Befehle betrifft, die durch die Handbuchseite beschrieben wird. .IP Die bevorzugten Ausdrücke für die verschiedenen Standards sind als Überschriften in \fBstandards\fP(7) aufgeführt. .IP 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.) .IP 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. .IP Wenn dieser Abschnitt nur aus einer Liste von Standards besteht (das ist üblicherweise der Fall), beenden Sie die Liste mit einem Punkt (\(aq.\(aq). .TP \fBNOTES\fP Verschiedene Anmerkungen .IP Für Handbuchseiten der Abschnitte 2 und 3 könnten die Aufnahme von Unterabschnitten (\fBSS\fP) \fILinux Notes\fP und \fIGlibc Notes\fP nützlich sein. .IP In Abschnitt 2 verwenden Sie die Überschrift \fIC library/kernel differences\fP, 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. .TP \fBBUGS\fP Eine Liste von Einschränkungen, bekannten Mängeln oder Unannehmlichkeiten und weiteren fragwürdigen Verhalten. .TP \fBEXAMPLES\fP Ein oder mehrere Beispiele für die Anwendung der Funktion, der Datei oder des Befehls .IP Wie Beispielprogramme geschrieben werden sollten, beschreibt der Abschnitt \fIBeispielprogramme\fP weiter unten. .TP \fBAUTHORS\fP Eine Liste der Autoren der Dokumentation oder des Programms .IP \fBVon einem AUTHORS\-Bereich wird entschieden abgeraten\fP. 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. .TP \fBREPORTING BUGS\fP Das Projekt \fIman\-pages\fP 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. .TP \fBCOPYRIGHT\fP Das Projekt \fIman\-pages\fP 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. .TP \fBSEE ALSO\fP Eine durch Kommata gegliederte Liste thematisch verwandter Handbuchseiten; manchmal folgen weitere Handbuchseiten oder Dokumente mit inhaltlichem Bezug .IP Die Liste sollte nach Abschnittsnummern und in den Abschnitten alphabetisch sortiert werden. Schließen Sie die Liste nicht mit einem Punkt ab. .IP Wenn die »SEE ALSO«\-Liste viele lange Namen von Handbuchseiten enthält, kann es zur Verbesserung der visuellen Darstellung sinnvoll sein, die Anweisungen \&\fI.ad l\fP (nicht rechts anordnen) und \fI.nh\fP (keine Silbentrennung) zu verwenden. Die Silbentrennung individueller Seitennamen können Sie vermeiden, indem Sie den Wörtern die Zeichenkette »\e%« voranstellen. .IP 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. .SH STIL\-RICHTLINIEN Die folgenden Unterabschnitte beschreiben den bevorzugten Stil für das Projekt \fIman\-pages\fP. 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. .SS "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. .SS "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, \fIselbst im Abschnitt SYNOPSIS\fP. .PP .\" Der Name des Befehls und seine Optionen sollten stets fett formatiert werden. .SS "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, \fIselbst im Abschnitt SYNOPSIS\fP, wobei der Rest der Funktion in fett spezifiziert wird: .PP \fB int meineFunktion(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP .PP Variablennamen sollten wie die Namen von Argumenten kursiv geschrieben werden. .PP 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 \fBfcntl\fP(2) Verweise auf das Thema der Seite als \fBfcntl\fP() geschrieben werden. Die empfohlene Schreibweise in der Quelldatei ist .PP .EX .BR fcntl (). .EE .PP .\" Die Verwendung dieses Formats anstatt »\efB…\efP()« erleichtert die Entwicklung von Werkzeugen für die Auswertung von Handbuch\-Quelltexten. .SS "Semantische Zeilenvorschübe verwenden " .\" Im Quelltext einer Handbuchseite sollten neue Sätze in einer neuen Zeile beginnen und lange Sätze an Interpunktionszeichen, welche die Satzteile voneinander abgrenzen (Komma, Semikolon, Doppelpunkt usw.), geteilt werden. Diese Konvention, im englischen zuweilen »Semantic newlines« (semantische Zeilenvorschübe) genannt, erleichtert es, die Wirkung von Patches zu beurteilen, welche oft auf Ebene einzelner Sätze oder Satzteile arbeiten. .SS "Formatierungskonventionen (Allgemeines)" Absätze sollten mit geeigneten Markierungen voneinander getrennt werden (üblicherweise entweder \fI.PP\fP oder \fI.IP\fP). Trennen Sie Absätze \fInicht\fP durch Einfügen von Leerzeilen, da diese Darstellungsfehler in einigen Ausgabeformaten verursachen (wie PostScript und PDF). .PP Dateinamen (ob Pfadnamen oder Verweise auf Header\-Dateien) werden immer kursiv gesetzt (z. B. \fI\fP), außer in der SYNOPSIS, wo eingefügte Dateien fett geschrieben werden (z. B. \fB#include \fP). 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. \fI\fP). .PP Spezielle Makros, die in der Regel mit Großbuchstaben geschrieben werden, werden in Fettdruck gesetzt (z.B. \fBMAXINT\fP). Ausnahme: Schreiben Sie NULL nicht fett. .PP Bei der Aufzählung einer Liste von Fehlercodes werden die Codes in Fettschrift geschrieben. (Diese Liste verwendet in der Regel das Makro \fB\&.TP\fP.) .PP Vollständige Befehle sollten, wenn sie lang sind, eine eigene, eingerückte Zeile bekommen, der eine Leerzeile vor\- und nachgestellt wird, zum Beispiel: .PP .in +4n .EX man 7 man\-pages .EE .in .PP Kurze Befehle können, kursiv gesetzt, in den laufenden Text aufgenommen werden; z. B. \fIman 7 man\-pages\fP. In diesem Fall kann es sich lohnen, an geeigneten Stellen in der Befehlszeile geschützte Leerzeichen ("\e\ ") zu verwenden. Befehlsoptionen sollten kursiv geschrieben werden (z. B. \fI\-l\fP). .PP 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. .PP Bei der Angabe von Shell\-Sitzungen sollte die Benutzereingabe stets fett formatiert werden, bespielsweise .PP .in +4n .EX $ \fBdate\fP Do Jul 7 13:01:27 CEST 2016 .EE .in .PP Jeder Verweis auf eine andere Handbuchseite sollte den Namen in Fettschrift darstellen und \fIimmer\fP ohne Leerzeichen von der Nummer des Abschnitts in Normalschrift (Roman) gefolgt werden; (z. B. \fBintro\fP(2)). Die empfohlene Schreibweise in der Quelldatei ist .PP .EX .BR intro (2). .EE .PP (Die Angabe der Abschnittsnummer in Querverweisen ermöglicht es Werkzeugen wie \fBman2html\fP(1), korrekte Hyperlinks zu erstellen.) .PP Steuerzeichen sollten in Fettschrift ohne Anführungszeichen geschrieben werden, beispielsweise \fB\(haX\fP. .SS Rechtschreibung Seit Release 2.39 folgen die \fIman\-pages\fP 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. .PP Abgesehen von den gut bekannten Rechtschreibunterschieden gibt es ein paar weitere Feinheiten, auf die Sie achten sollten: .IP * 3 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. .SS BSD\-Versionsnummern Das klassische Schema zum Schreiben von BSD\-Versionsnummern lautet \fIx.yBSD\fP, wobei \fIx.y\fP die Versionsnummer ist (z.B. 4.2BSD). Vermeiden Sie Formen der Art \fIBSD 4.3\fP. .SS 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: .PP .EX .SS Unicode under Linux .EE .\" .SS "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 \fI.in\ +4n\fP und \fI.in\fP), formatieren Sie sie mittels der Makros \fI.EX\fP und \fIEE\fP und schließen Sie sie mit geeigneten Absatzmarkierungen (entweder \fI.PP\fP oder \fI.IP\fP) ein. Beispiel: .PP .in +4n .EX .PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PP .EE .in .SS "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. .TS l l l --- l l l. Begriff Nicht verwenden Hinweise bit mask bitmask built\-in builtin Epoch epoch T{ Für den Beginn der UNIX\-Zeitrechnung (00:00:00, 1. Januar 1970 UTC) T} 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 T{ reserved port, system port T} real\-time T{ realtime, real time T} run time runtime saved set\-group\-ID T{ saved group ID, saved set\-GID T} saved set\-user\-ID T{ saved user ID, saved set\-UID T} set\-group\-ID set\-GID, setgid set\-user\-ID set\-UID, setuid superuser T{ super user, super\-user T} superblock T{ super block, super\-block T} timestamp time stamp timezone time zone uppercase upper case, upper\-case usable useable user space userspace username user name x86\-64 x86_64 T{ Außer beim Verweis auf das Ergebnis von »uname\ \-m« oder ähnlichem T} zeros zeroes .TE .PP Siehe auch den nachfolgenden Abschnitt \fIBindestriche in attributiven Zusammensetzungen\fP. .SS "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. .TS l l l --- l l l. Vermeiden Stattdessen Hinweise 32bit 32\-bit T{ ebenfalls für 8\-bit, 16\-bit usw. T} current process calling process T{ Ein häufiger Fehler der Kernel\-Programmierer beim Schreiben von Handbuchseiten T} manpage T{ man page, manual page T} 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 .TE .SS "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: .PP DG/UX HP\-UX UNIX UnixWare .SS "NULL, NUL, Null\-Zeiger und Null\-Zeichen" Ein \fInull pointer\fP ist ein Zeiger, der auf nichts verweist. Er wird normalerweise durch die Konstante \fINULL\fP angegeben. Andererseits bezeichnet \fINUL\fP das \fINULL\-Byte\fP, ein Byte mit dem Wert 0, das in C durch die Zeichenkonstante \fI\(aq\e0\(aq\fP ausgedrückt wird. .PP Der bevorzugte Begriff für den Zeiger ist »null pointer« oder einfach »NULL«, bitte schreiben Sie nicht »NULL pointer«. .PP 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«. .SS Hyperlinks Verwenden Sie für Hyperlinks das Makropaar \fI.UR\fP/\fI.UE\fP (siehe \fBgroff_man\fP(7)). Dieses erzeugt intakte Hyperlinks, die in einem Webbrowser geöffnet werden können, wenn die Seite etwa folgendermaßen dargestellt wird: .PP BROWSER=firefox man \-H Seitenname .SS "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«. .PP Die einzige Stelle, wo solche Abkürzungen akzeptabel sind, ist in \fIkurzen\fP in Klammern gesetzten Anmerkungen (z.B. wie in dieser hier). .PP Verwenden Sie stets Punkte in solchen Abkürzungen, wie hier gezeigt. Zusätzlich sollte auf »e.g.« und »i.e.« stets ein Komma folgen. .SS Em\-Gedankenstriche Einen em\-Gedankenstrich – das Zeichen, das an beiden Enden dieses Satzteiles steht –, setzen Sie in *roff mit dem Makro »\e(em«. (Auf einem ASCII\-Terminal wird ein em\-Gedankenstrich üblicherweise als zwei Bindestriche, in anderen typografischen Kontexten als langer Gedankenstrich dargestellt.) Em\-Gedankenstriche sollten \fIohne\fP vor\- und nachstehendes Leerzeichen geschrieben werden. .SS "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: .PP 32\-bit value command\-line argument floating\-point number run\-time check user\-space function wide\-character string .SS "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: .PP interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem .PP 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: .PP non\-ASCII non\-English non\-NULL non\-real\-time .PP .\" Beachten Sie auch, dass »re\-create« und »recreate« zwei Verben unterschiedlicher Bedeutung sind. Das erstere dürfte vermutlich jenes sein, was Sie benötigen. .SS "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 \fButf\-8\fP(7) oder bei Optionen mit einem vorangestelltem Bindestrich, wie in \fIls\ \-l\fP, verwenden Sie die folgende Form im Quelltext der Handbuchseite: .PP \e\- .PP Diese Richtlinie gilt auch für Code\-Beispiele. .PP Um einfache Anführungszeichen zu verwenden, die in ASCII, in UTF\-8 und in PDF korrekt dargestellt werden können, verwenden Sie "\e(aq" ("Apostroph\-Zitatzeichen"); zum Beispiel .PP \e(aqC\e(aq .PP wobei \fIC\fP das zitierte Zeichen ist. Diese Richtlinie ist auch auf Zeichenkonstanten und in code\-Beispielen anzuwenden. .PP Wo ein korrektes Zirkumflex\-Zeichen (\(ha) benötigt wird, das sowohl im Terminal als auch im PDF gut dargestellt wird, verwenden Sie »\e(ha«. Dies ist insbesondere in Beispielcode erforderlich, um in der daraus erzeugten PDF\-Darstellung ein ansehnliches Zirkumflex zu erhalten. .PP .\" Die Verwendung eines nackten »\(ti«\-Zeichens führt zu einer fehlerhaften Darstellung in PDF. Verwenden Sie stattdessen »\e(ti«. Dies ist insbesondere in Beispielcode erforderlich, um in der daraus erzeugten PDF\-Darstellung eine ansehnliche Tilde zu erhalten. .SS "Beispielprogramme und Shell\-Sitzungen" Handbuchseiten können Beispielprogramme enthalten, die den Gebrauch von Systemaufrufen oder Bibliotheksfunktionen beschreiben. Beachten Sie jedoch das Folgende: .IP * 3 Beispielprogramme sollten in C geschrieben sein. .IP * 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. .IP * 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. .IP * Ausdrucksstarker Code und hilfreiche Kommentare sind sehr begrüßenswert. .IP * Beispielprogramme sollten nach dem Aufruf von System\- und Bibliotheksfunktionen prüfen, ob Fehler aufgetreten sind. .IP * Beispielprogramme sollten vollständig sein und keine Warnungen ausgeben, wenn sie mit \fIcc\ \-Wall\fP kompiliert werden. .IP * 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). .IP * 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: .IP indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .IP * Aus Konsistenzgründen sollten alle Beispielprogramm mit einer der folgenden Sequenzen beendet werden: .IP exit(EXIT_SUCCESS); exit(EXIT_FAILURE); .IP Vermeiden Sie die folgenden Formen, um ein Programm zu beenden: .IP exit(0); exit(1); return n; .IP * Falls ein umfangreicher erklärender Text vor dem Programm\-Quellcode steht, markieren Sie den Quellcode mit der Zwischenüberschrift \fIProgram source\fP, wie in: .IP \&.SS Program source .IP Tun Sie dies immer, wenn der erklärende Text ein Sitzungsprotokoll der Shell enthält. .PP Wenn Sie eine Shell\-Sitzung einfügen, welche die Verwendung eines Programms oder andere Möglichkeiten des Systems demonstriert: .IP * 3 Setzen Sie das Sitzungsprotokoll vor die Quellcode\-Auflistung. .IP * Rücken Sie das Sitzungsprotokoll um vier Zeichen ein. .IP * Wählen Sie Fettschrift für vom Benutzer eingegebenen Text, um ihn von der vom System erzeugten Ausgabe zu unterscheiden. .PP In \fBwait\fP(2) und \fBpipe\fP(2) finden Sie vorbildliche Beispielprogramme. .SH BEISPIELE Kanonische Beispiele für die Gestaltung von Handbuchseiten für das \fIman\-pages\fP\-Paket sind \fBpipe\fP(2) und \fBfcntl\fP (2). .SH "SIEHE AUCH" \fBman\fP(1), \fBman2html\fP(1), \fBattributes\fP(7), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), \fBmdoc\fP(7) .SH KOLOPHON Diese Seite ist Teil der Veröffentlichung 5.10 des Projekts Linux\-\fIman\-pages\fP. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter \%https://www.kernel.org/doc/man\-pages/. .SH ÜBERSETZUNG Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer , Mario Blättermann , Stephan Beck , Dr. Tobias Quathamer und Helge Kreutzmann erstellt. Diese Übersetzung ist Freie Dokumentation; lesen Sie die .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Version 3 .UE 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 .MT debian-l10n-german@\:lists.\:debian.\:org Mailingliste der Übersetzer .ME .