Richtlinien zur Erstellung deutscher Handbuchseiten
Kapitel 4 - Formalia

4.1 Hervorhebungen

In vielen Handbuchseiten werden Textstellen wie folgt hervorgehoben:

       Dieser Text ist \fBfett\fR und dieser \fIkursiv\fR.

Dadurch wird der Quellcode weniger leicht zu lesen und Änderungen lassen sich auch nur schlecht vornehmen und überblicken. Besser ist daher folgende Methode, die auch benutzt werden soll.

       Dieser Text ist
       .B fett
        und dieser
       .IR kursiv .

Die folgenden Schriftarten können auf diese Weise gemischt werden.

        .BR fett normal fett
        .BI fett kursiv fett
        .IR kursiv normal kursiv
        .IB kursiv fett kursiv
        .RB normal fett normal
        .RI normal kursiv normal

Die Parameter des Schriftsatzbefehls werden alternierend in den gewünschten Schriftarten dargestellt. Zu beachten ist dabei jedoch, daß beim Umschalten kein Leerzeichen eingefügt wird. Das ist nur dann der Fall, wenn ein Zeilenbruch verwendet wird. Wenn in der Zeile jedoch ein Leerzeichen gewünscht ist, muß der Parameter samt Leerzeichen in Anführungszeichen gesetzt werden.

        .BR track1 ", " track2 " und " track3

Wenn drei Schriftarten in einer Zeile oder Absatz verwendet werden sollen, läßt es sich teilweise kaum vermeiden, doch mit Konstrukten wie "\fBfett\fR" zu arbeiten, um in die dritte Schriftart umzuschalten.

4.2 Leerzeichen

Hinter einem Punkt `.' am Satzende sollten zwei (!) Leerzeichen stehen. Roff macht dieses automatisch, wenn der Satz am Zeilenende endet. Das fördert die Lesbarkeit des Textes.

4.3 Aufzählungen

Werden Aufzählungen benutzt (z.B. im Abschnitt OPTIONEN oder FEHLER), dann darf dort keine Maßangabe verwendet werden. Korrekt ist z.B. diese Aufzählung:

       Text
       .TP
       .B GLOB_DOOFS
       bedeutet, daß
       [..]
       .PP
       Text

4.4 Abschnitt "ÜBERSICHT"

In diesem Abschnitt gibt es definierte Zeilenabstände und definierte Hervorhebungen (siehe man(7)). Zwischen Include-Dateien und Funktionskopf kommt eine Leerzeile. Realisiert wird das wie folgt.

       .nf
       .B #include <glob.h>
       .sp
       .BI "int glob(const char *" pattern ", int " flags ","
       .nl
       .BI "         int " errfunc "(const char * " epath ", int " eerrno ),
       .nl
       .BI "         glob_t " "*pglob" );
       .nl
       .BI "void globfree(glob_t *" pglob ");"
       .fi

4.5 Abschnitt "SIEHE AUCH"

In vielen Handbuchseiten werden mehrere Referenzen in eine Zeile geschrieben, wild mit Hochkommas aneinandergereiht, damit der Name fett, die Zahl in Klammern jedoch normal dargestellt wird. Ich bitte euch, diese Verweise ein wenig anders zu schreiben, nämlich nur einen Verweis pro Zeile. Dadurch werden die Referenzen übersichtlicher und man kann leichter weitere hinzufügen oder herausnehmen. Statt folgender Zeile

       .BR fgetpwent "(3), " getpwent "(3), " setpwent (3),

sollte folgende geschrieben werden:

       .BR fgetpwent (3),
       .BR getpwent (3),
       .BR setpwent (3),

Richtlinien zur Erstellung deutscher Handbuchseiten

7. Februar 2008

Martin Schulze, joey@infodrom.org