  Richtlinien zur Erstellung deutscher Handbuchseiten
  Martin Schulze, joey@linux.de
  18. May 1996

  Dieses Dokument soll Richtlinien zur Erstellung deutscher Handbuch-
  seiten fuer das manpages-de-Projekt beschreiben.  Das Projekt wird
  geleitet von Martin Schulze <http://home.pages.de/~joey/> (Mar-
  tin.Schulze@Infodrom.North.DE).  Ein Grossteil stammt von Michael
  Haardt.

  1.  Grundsaetzliches


  Die Handbuchseiten sollten nicht wort-woertlich uebersetzt werden,
  sondern sinngemaess.  Hier zaehlt nicht, dem Englischlehrer zu
  imponieren oder ihm eine gute Zensur abzuringen, sondern den Leuten
  den Inhalt der Seiten verstaendlich darzulegen.

  Bitte achtet bei den Uebersetzungen auf korrekten Satzbau.  Im
  Englischen ist der Satzbau oft anders als im Deutschen und uebersetzt
  klingt es of geholpert.

  Allgemein sei auf die Seite man(7) hingewiesen, in der
  Grundsaetzliches zur Gestaltung von Handbuchseiten diskutiert wird.


  1.1.  Kopfzeile


  Kopfzeilen sehen wie folgt aus:


   .TH GLOB 3 "13. Mai 1996" "GNU" "Bibliotheksfunktionen"



  Bitte denkt dran, das Datum zu aendern, wenn ihr die Seite uebersetzt
  habt.

  Der Text vor der Kopfzeile, also die jeweilige Policy, Aenderungen
  etc. sollen nicht mit uebersetzt werden.  Jedoch soll sich der oder
  die Uebersetzer/in hier verewigen mit einer Zeile aehnlich der
  folgenden:


    .\" Translated into german by Martin Schulze (joey@infodrom.north.de)



  Zwischen diesen Kommentaren und der o.g. Kopfzeile soll eine leere
  Kommentarzeile stehen:


    .\"




  1.2.  Aenderungen


  Wenn ihr Fehler in den Handbuchseiten entdeckt, inhaltliche oder
  formelle, dann aendert sie bitte und schickt Andries Brouwer
  (aeb@cwi.nl) den Patch.


  2.  Tips fuer die Uebersetzung



  2.1.  Abschnitte


  Die Abschnitte (.SH) sollen wie folgt uebersetzt werden:


   .SH NAME               .SH BEZEICHNUNG
   .SH SYNOPSIS           .SH "UeBERSICHT"
   .SH DESCRIPTION        .SH BESCHREIBUNG
   .SH OPTIONS            .SH OPTIONEN
   .SH "RETURN VALUE"     .SH "RUeCKGABEWERT"
   .SH CONFIG             .SH KONFIGURATION
   .SH "CONFORMING TO"    .SH "KONFORM ZU"
   .SH DIAGNOSTICS        .SH DIAGNOSE
   .SH ENVIRONMENT        .SH UMGEBUNGSVARIABLEN
   .SH ERRORS             .SH FEHLER
   .SH EXAMPLE            .SH BEISPIEL
   .SH EXAMPLES           .SH BEISPIELE
   .SH FILES              .SH DATEIEN
   .SH HISTORY            .SH GESCHICHTE
   .SH NOTES              .SH ANMERKUNGEN
   .SH REMARKS            .SH BEMERKUNGEN
   .SH RESTRICTIONS       .SH EINSCHRAeNKUNGEN
   .SH WARNING            .SH WARNUNG
   .SH BUGS               .SH BUGS
   .SH "SEE ALSO"         .SH "SIEHE AUCH"
   .SH AUTHOR             .SH AUTOR




  2.2.  Kapitel


  Die Kapitel in der Kopfzeile sollen wie folgt uebersetzt werden.


    1 Dienstprogramme fuer Benutzer
    2 Systemaufrufe
    3 Bibliotheksfunktionen
    4 Geraetedateien
    5 Dateiformate
    6 Spiele und Demonstrationen
    7 Verschiedenes
    8 Dienstprogramme zur Systemverwaltung
    9 Kernelfunktionen




  2.3.  Englisch -> Deutsch


  Und hier nun einige praktische Tips:


    manual                Handbuch
    library               Bibliothek
    linker                Binder / Linker
    Compiler              Compiler
    file descriptor       Dateikennzahl / Dateideskriptor

  Die Problematik ist die, dass man eine Seite nicht mehr oder nur noch
  schwer verstehen kann, wenn gerade Fachausdruecke mit uebersetzt
  werden.  Hier sollte der beruehmte goldene Mittelweg gefunden werden.


  3.  Formalia



  3.1.  Hervorhebungen


  In vielen Handbuchseiten werden Textstellen wie folgt hervorgehoben:


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



  Dadurch wird der Source schlecht lesbar und Aenderungen lassen sich
  auch nur schlecht vornehmen.  Besser ist folgende Methode, die auch
  benutzt werden soll.


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




  3.2.  Leerzeichen


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


  3.3.  Aufzaehlungen


  Werden Aufzaehlungen benutzt (z.B. im Abschnitt OPTIONEN oder FEHLER),
  dann darf dort keine Massangabe verwendet werden.  Korrekt ist z.B.
  folgendes:


    Text
    .TP
    .B GLOB_DOOFS
    bedeutet, dass
    [..]
    .PP
    Text




  3.4.  Abschnitt "UeBERSICHT"


  In diesem Abschnitt gibt es definierte Zeilenabstaende 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




  3.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, naemlich
  nur einen Verweis pro Zeile.  Dadurch werden die Referenzen
  uebersichtlicher und man kann leichter weitere hinzufuegen 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),


























