  DLHP Autor HOWTO
  Marco Budde (Budde@tu-harburg.de)
  v1.7, 1. Januar 2002

  Diese HOWTO richtet sich an Autoren und bersetzer der deutschen Linux
  HOWTOs.


  1.  Einleitung

  1.1.  Ziel dieser HOWTO

  Diese HOWTO sollte jeder lesen, der eine deutsche Linux HOWTO
  schreiben oder eine englische ins Deutsche bersetzen mchte.  Es wird
  beschrieben, wie eine HOWTO genau formatiert werden sollte. Dieses ist
  wichtig, damit alle deutschen HOWTOs hnlich aussehen und den gleichen
  Qualittsansprchen gengen.

  Falls Sie der Meinung sind, da man einige der hier beschriebenen
  Sachen besser machen knnte, zgern Sie bitte nicht und schicken Sie
  mir ein E-Mail.


  1.2.  Copyright

  Dieses Dokument ist urheberrechtlich geschtzt. Das Copyright liegt
  bei Marco Budde.
  Das Dokument darf gem der GNU General Public License verbreitet
  werden.  Insbesondere bedeutet dieses, da der Text sowohl ber
  elektronische wie auch physikalische Medien ohne die Zahlung von
  Lizenzgebhren verbreitet werden darf, solange dieser Copyright
  Hinweis nicht entfernt wird. Eine kommerzielle Verbreitung ist erlaubt
  und ausdrcklich erwnscht. Bei einer Publikation in Papierform ist
  das Deutsche Linux HOWTO Projekt hierber zu informieren.


  2.  Grundlagen

  2.1.  Wie kann ich mich am DLHP beteiligen?


  Wenn Sie selbst eine HOWTO bersetzen oder eine eigene schreiben
  mchten, erreichen Sie den Herausgeber des DLHP unter:


       Internet: Budde@tu-harburg.de


  Um sicherzustellen, da nicht eine HOWTO von mehreren Leuten
  bearbeitet wird, mssen Sie dem Herausgeber unbedingt zuerst
  mitteilen, welche HOWTO Sie bearbeiten wollen, bevor Sie anfangen.

  Wenn Sie eine englische HOWTO bersetzen mchten, knnen Sie sich
  selbst eine aussuchen, die Sie bearbeiten mchten. Gehen Sie dabei
  folgendermaen vor:


  1. Suchen Sie sich eine interessante HOWTO von folgendem Server aus:

       http://www.linuxdoc.org/docs.html#howto



  2. Schauen Sie in DE-HOWTO nach, ob diese HOWTO nicht bereits
     bersetzt wurde oder sich gerade in Arbeit befindet.

  3. Teilen Sie dem Herausgeber die ausgesuchte HOWTO mit.

  Nach einiger Zeit sollte Ihre HOWTO dann auch in DE-HOWTO auftauchen.
  Falls dieses nicht der Fall ist, der Herausgeber kann ja auch mal was
  vergessen :), weisen Sie den Herausgeber bitte unbedingt darauf hin.


  2.2.  Qualittsanspruch des DLHPs


  Das Deutsche Linux HOWTO Projekt hat es sich zum Ziel gesetzt,
  deutschsprachige Linux Dokumentation mit einer hohen Qualitt zu
  verffentlichen. Das bedeutet fr die Autoren:


    Die HOWTOs sollten mglichst fehlerfrei sein und nicht nur aus
     Rechtschreibfehlern und Tippfehlern bestehen. Das bedeutet nicht,
     da jeder Autor studierter Germanist sein sollte, aber eine
     gewissen Qualitt ist notwendig.

    Die Texte sollten leicht verstndlich und lesbar sein. Dieses ist
     insbesondere bei bersetzungen immer ein Problem, da wrtliche
     bersetzungen hufig schwierig zu verstehen sind.

    Die HOWTOs sollten inhaltlich korrekt sein. Insbesondere bei
     bersetzungen von LDP HOWTOs sollte unbedingt vorher berprft
     werden, ob die HOWTO es berhaupt wert ist, bersetzt zu werden.
     Leider gibt es beim LDP anscheinend keine Qualittskontrolle, so
     da viele LDP HOWTOs teilweise bis vllig falsch sind.

    Es wird viel Wert auf die Einhaltung der Formatierungsrichtlinien
     dieser HOWTO gelegt. Durch eine vernnftige und vor allem
     einheitliche Formatierung sind die HOWTOs fr die Anwender
     wesentlich besser lesbar.

  Der Herausgeber erhlt leider sehr hufig fertige HOWTOs von
  bersetzern und Autoren, die sich in einem vllig unausgereiften
  Zustand befinden. Um diese HOWTOs fr die Verffentlichung auf der
  DLHP-Homepage fertig zu machen, mu der Herausgeber teilweise
  vermutlich mehr Zeit investieren wie der bersetzer bzw. Autor. Hierzu
  fehlt es dem Herausgeber an Zeit und vor allem Lust.

  Es werden auf der Homepage des DLHPs grundstzlich nur HOWTOs
  verffentlicht, die diesen Qualittsansprchen entsprechen.


  2.3.  Was tun nach der bersetzung?


  Fertige HOWTOs schicken Sie dem Herausgeber bitte per E-Mail an seine
  E-Mail-Adresse. Schicken Sie bitte nur den SGML-Source, den sie vorher
  mit gzip oder bzip2 komprimiert haben, im MIME base64 Format. Bitte
  achten Sie unbedingt auf die Komprimierung.

  Bedenken Sie bitte, da auch die Zeit des Herausgebers begrenzt ist
  und er nicht die Zeit hat, bei jeder HOWTO Formatierungs- und SGML-
  Fehler zu beseitigen. Lesen Sie am besten, bevor Sie den Source
  abschicken, noch einmal diese HOWTO vollstndig durch und berprfen
  Sie, ob Sie nichts vergessen haben.

  Testen Sie also unbedingt vorher, ob sich Ihr Source in alle
  verwendeten Formate ohne Fehler bersetzen lt und ob die
  Formatierung der hier beschriebenen entspricht. Zum Test knnen Sie
  folgenden Makefile benutzen:


       http://www.tu-harburg.de/dlhp/FTP/tools/Makefile



  Denken Sie bitte an die Klrung des Copyrights; siehe ``Copyright der
  HOWTOs''.

  Nachdem Sie Ihre HOWTO abgeschickt habe, schreiben Sie bitte zuerst
  keine weiteren Updates. Der DLHP-Herausgeber wird die eingehenden
  Versionen berprfen und eventuelle Fehler beseitigen.  Dieser Proze
  kann - gerade bei der ersten Version - einige Zeit dauern. Sie knnen
  diesen Proze dadurch beschleunigen, da Sie sich von Anfang an
  mglichst genau an die Ratschlge in dieser HOWTO halten.

  Nachdem die HOWTO vom DLHP-Herausgeber bearbeitet worden ist, wird sie
  auf unserer Homepage verffentlicht. Benutzen Sie dann bitte den auf
  der Homepage gespeicherten SGML-Source Ihrer HOWTO fr sptere
  Updates. Und schauen Sie sich mal mit



       diff -u <ihre version.sgml> <fertige version.sgml>





  die nderungen an, die der DLHP-Herausgeber an Ihrem Text vorgenommen
  hat. Dieses kann hilfreich sein, um die gleichen Fehler bei spteren
  Updates nicht wieder einzubauen.



  2.4.  sgml-tools

  Zur Formatierung der HOWTOs wird das Programmpaket sgml-tools
  verwendet. Dieses Paket erlaubt es, mittels einer SGML-Quelldatei die
  Formate HTML, ASCII, LaTeX (DVI), PostScript und Adobe Acrobat (PDF)
  zu erzeugen.

  Die Verwendung der sgml-tools bietet sich an, da man so leicht
  verschiedene Formate erzeugen kann und alle HOWTOs dadurch hnlich
  aussehen.

  Die verwendete Version 1.0.9 der sgml-tools liegt den meisten Linux
  Distributionen als Paket bei. Ansonsten ist das Programm hier zu
  bekommen:


       http://www.sgmltools.org


  Die offizielle Version 1.0.9 lt sich mit aktuellen Compilern nicht
  mehr bersetzen. Auf der DLHP-Homepage ist deswegen ein vernderter
  Source zu finden, bei dem der verwendete SGML-Parser durch eine
  aktuellere Version ausgetauscht wurde:


       http://www.tu-harburg.de/dlhp/FTP/tools/sgml-tools_1.0.9.tar.bz2


  Auf keinen Fall kann die Version 2.x benutzt werden, da diese vllig
  inkompatibel zur alten ist und noch nicht ausgereift ist. Auerdem
  wurde die Entwicklung der 2.x Version anscheinend eingestellt.

  Speziell fr das DLHP gibt es einen Patch fr die sgml-tools, der hier
  zu finden ist:


       http://www.tu-harburg.de/dlhp/FTP/tools/


  Diese Version enthlt einige Bugfixes, ein verbessertes Aussehen der
  formatierten Dokumente und PDF-Support. Damit der PDF-Support
  fehlerfrei funktioniert, mu Ghostscript in mindestens Version 4.x und
  teTeX in mindestens der Version 0.9 auf dem Rechner installiert sein.



  2.5.  Vorlagen

  Fr die bersetzung einer HOWTO empfiehlt es sich, den SGML Source der
  entsprechenden HOWTO von

       http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/


  zu beziehen und als Grundlage fr die bersetzung zu verwenden.

  Hierbei sollte man jedoch unbedingt beachten, da die LDP HOWTOs auf
  einer anderen Formatierungsrichtlinie beruhen. Man kann also nicht
  einfach die bestehende Formatierung bernehmen, sondern mu diese
  eventuell an die in diesem Dokument beschriebene anpassen.
  2.6.

  Copyright der HOWTOs

  Wenn Sie eine englische HOWTO bersetzen, berprfen Sie bitte das
  Copyright der englischen HOWTO. Die HOWTOs des DLHP sollen mglichst
  alle der GNU General Public License unterliegen.

  Falls das beim Original nicht der Fall sein sollte, fragen Sie bitte
  beim Autor nach, ob wir die deutsche Version unter der GPL verbreiten
  knnen. Und fragen Sie den Autor wirklich und ndern Sie nicht einfach
  nur die Lizenz. Bei Urheberrechtsverstssen haftet der bersetzer und
  nicht das DLHP! Leiten Sie bitte eine Kopie der Erlaubnis an der
  Herausgeber weiter.

  Die HOWTO sollte irgendwo in der Einleitung - meistens das erste
  Kapitel - einen Copyright Hinweis wie den folgenden enthalten:



       <sect1>Copyright
       <p>

       Dieses Dokument ist urheberrechtlich geschtzt. Das Copyright fr
       die englische <em/AX25 HOWTO/, auf der dieses Dokument basiert,
       liegt bei Terry Dawson. Das Copyright fr die deutsche Version
       liegt bei Gerd Rthig und Marco Budde.

       Das Dokument darf gem der GNU <em><htmlurl url="DE-GPL.html"
       name="General Public License"></em> verbreitet werden.
       Insbesondere bedeutet dieses, da der Text sowohl ber
       elektronische wie auch physikalische Medien ohne die Zahlung von
       Lizenzgebhren verbreitet werden darf, solange dieser
       Copyright-Hinweis nicht entfernt wird. Eine kommerzielle Verbreitung
       ist erlaubt und ausdrcklich erwnscht. Bei einer Publikation in
       Papierform ist das Deutsche Linux HOWTO Projekt hierber zu
       informieren.




  Hierbei sollten alle Leute, die mehr als einen Satz zu dem Dokument
  beigetragen haben, erwhnt werden.

  Sollten Sie keine HOWTO bersetzen, sondern eine eigene schreiben, so
  verwenden Sie bitte auch die GNU GPL. Denn zu einem freien
  Betriebssystem gehrt auch eine freie Dokumentation.



  2.7.  SGML Header

  Jedes SGML Dokument beginnt mit einem Header wie dem folgendem:













  <!--
    Dieser SGML Source kann mit dem Programmpaket sgml-tools 1.0.x in
    die Formate TXT, HTML, DVI, Postscript und PDF umgewandelt werden.
    Bei allen Konvertern mu die Option "-c latin -l de"
    verwendet werden.

    Deutsches Linux HOWTO Projekt
       http://www.tu-harburg.de/dlhp/
  -->

  <!doctype linuxdoc system>

  <article>

  <title>Linux foo HOWTO
  <author>Name1 (<tt>name1@foo.org</tt>) und
          Name2 (<tt>name2@foo.org</tt>)
  <date>v1.0, 1. April 1998
  <abstract>
  kurze Inhaltsangabe, hoechstens drei Zeilen
  </abstract>

  <toc>

  [ ... ]

  </article>




  Als Autor sollte der Autor der englischen HOWTO (Name1) und der
  bersetzer (Name2) angegeben werden. Unter <date> wird die
  Versionsnummer gefolgt vom Datum angegeben. Falls es sich um eine
  reine bersetzung handelt, kann die Versionsnummer des Originals
  verwendet werden. Als Datum wird nicht das Datum des Originals
  verwendet, sondern das der Erstellung der bersetzung.


  2.8.  Umlaute


  Die Umlaute sollen in den formatierten Dokumenten in der Form  und
  nicht in der Form ue erscheinen. Die sgml-tools bieten zwei
  Mglichkeiten, die Umlaute einzugeben:


    Latin-1 Zeichensatz (8 Bit): 

    HTML Form (7 Bit): &uuml;

  Wenn mglich, sollte die erste Mglichkeit gewhlt werden, da man so
  den Source mit jedem Editor gut lesen kann.



  2.9.  Du oder Sie?

  Bei bersetzungen stellt sich immer die Frage, wie man am besten you
  bersetzt. Da Linux schon lange nicht mehr nur von einer kleinen
  Gruppe von Insidern benutzt wird, ist es sicherlich sinnvoll, den
  Benutzer mit Sie anzureden, da ansonsten eventuell schnell der
  falsche Eindruck entstehen knnte, da sich die HOWTOs nur an einen
  kleinen Kreis von Programmierern und Administratoren richten.


  Da die Frage schon mehrfach aufgetaucht ist: das Sie bezieht sich
  natrlich nur auf die Texte selbst. Die Autoren selbst duzen sich in
  der Regel =:).



  2.10.  SGML-Sourcen


  Achten Sie bitte darauf, da Ihr SGML-Source vernnftig lesbar ist.

  Dazu gehrt es z.B., da die Zeilen nach sptestens 80 Zeichen
  umgebrochen werden. Bei langen URLs oder hnlichen Dinge kann
  natrlich eine Ausnahme gemacht werden. Flietext wird nicht
  akzeptiert, da sich dieser nicht vernnftig lesen und bearbeiten lt.

  Fgen Sie zwischen den einzelnen Abschnitten ruhig ein paar Leerzeilen
  ein. Auch ansonsten schaden Leerzeilen der Lesbarkeit nicht.



  3.  Formatierung

  3.1.  Dateinamen

  Die Namen von Dateien und Pfaden werden es solche durch die Verwendung
  der Typewriter-Schrift gekennzeichnet:



       ... die Datei <tt>/etc/inittab</tt> sollte ...




  Dieses gilt auch fr Programmnamen, wenn damit die ausfhrbare Datei
  gemeint ist. Also z.B.:



       ... mit <tt>lilo</tt> wird der ...

       ... das Programmpaket LILO ist sehr weit verbreit ...






  3.2.  FTP-Adressen


  Eine FTP-Adresse soll im Dokument immer in der Form

       sunsite.unc.edu:/pub


  auftauchen. Die Form

       ftp://sunsite.unc.edu/pub


  findet keine Verwendung.

  Meistens soll die FTP-Adresse im HTML-Dokument auch anklickbar sein.
  Im SGML-Source wrde man also folgendes verwenden:
       <tscreen><htmlurl url="ftp://metalab.unc.edu/pub"
                         name="metalab.unc.edu:/pub"></tscreen>




  Das <tscreen> sorgt dafr, da die Zeile in Typewriter Schrift und in
  einer seperaten Zeile dargestellt wird.  Dieses ist sinnvoll, da es
  ansonsten zu Umbruchproblemen in der LaTeX-Version kommen kann. Falls
  es sich um eine sehr kurze Adresse handelt, kann statt dessen auch
  <tt> benutzt werden.


  3.3.  HTTP-Adressen

  HTTP-Adressen sehen fast genauso wie die FTP-Adressen aus. Auch hier
  findet meistens <tscreen> statt <tt> Verwendung:



       <tscreen><htmlurl url="http://www.foo.de/foo/"
                 name="http://www.foo.de/foo/"></tscreen>




  Falls Sie wie in diesem Beispiel nur das Verzeichnis und nicht auch
  den Dateinamen (z.B. index.html) angeben, achten Sie bitte darauf, da
  das letzte Zeichen ein Slash ist. Hierdurch wird unntiger HTTP-
  Verkehr vermieden.



  3.4.  Mailadressen

  Eine E-Mail-Adresse wird meistens in folgender Form gesetzt:


       Thomas Mustermann (<tt><htmlurl url="mailto:tm@entenhausen.de"
                          name="tm@entenhausen.de"></tt>)







  3.5.  Dokumente

  Falls Sie im Text auf andere Dokumente verweisen, schlieen Sie den
  Titel bitte in <em> ein.

  Verweise auf andere HOWTOs sollten auf jeden Fall anklickbar sein.
  Falls es sich bei der anderen HOWTO um eine HOWTO handelt, die bereits
  als deutsche bersetzung existiert, wird ein relativer Link benutzt.
  Ein Link auf die PPP HOWTO wrde also z.B.  so aussehen:



       <em><htmlurl url="DE-PPP-HOWTO.html" name="PPP HOWTO"></em>




  So funktionieren die Links nicht nur im Internet sondern auch im
  privaten Intranet.
  Beachten Sie bitte, da PPP HOWTO ohne Bindestrich geschrieben wird.

  Falls der Link auf eine englische HOWTO gehen soll, benutzt man einen
  Link auf die sunsite:



       <em><htmlurl url="http://www.linuxdoc.org/HOWTO/PPP-HOWTO.html"
                    name="PPP HOWTO"></em>






  3.6.  Listings, Kommandozeile

  Listings und Beispiele fr die Eingabe werden mit <tscreen><verb>
  formatiert. Die <code> Umgebung wird nicht benutzt.

  Bei Listings sollten unbedingt auch die Kommentare im Listing ins
  Deutsche bersetzt werden. Gehen Sie immer davon aus, da der Leser
  kein Wort Englisch versteht :).

  Achten Sie unbedingt auf die Zeilenlnge. Mehr als 60-70 Zeichen
  sollte eine Zeile auf keinen Fall enthalten. Sonst gibt es in der
  ASCII und der Druckversion Probleme.

  Zu lange Zeilen mssen so umformuliert werden, da sie die
  Lngenbeschrnkung erfllen. Hierbei ist darauf zu achten, da die
  Listings bzw. Kommandos weiterhin vom Syntax her korrekt sind.

  Bei einem bash-Skript wrde man z.B. statt



       ...
       foo -o /usr/local/etc/foo/footab -o /etc/foo/footab
       ...




  folgende Formulierung benutzen:



       ...
       foo -o /usr/local/etc/foo/footab \
           -o /etc/foo/footab
       ...




  Bei anderen Sprachen mu man natrlich anders vorgehen.

  Bildschirmausgaben lassen sich oftmals dadurch anpassen, da man die
  Anzahl der Leerzeichen verringert.



  3.7.  Verweise auf andere Abschnitte



  Falls Sie sich in Ihrer HOWTO auf einen anderen Abschnitt Ihrer HOWTO
  beziehen wollen, schreiben Sie bitte nicht einfach sowas wie weitere
  Informationen finden Sie in Sektion 3. Das fhrt sehr schnell zu
  Problemen, wenn Sie weitere Abschnitte einfgen.

  Die sgml-tools bieten fr diesen Zweck die beiden Befehle <label> und
  <ref>. Mit <label> markieren Sie den Abschnitt, auf den Sie sich
  beziehen mchten.

  Bei Verwendung des <label>-Befehls, sorgen Sie bitte dafr, da Ihre
  Labels nicht mit den in anderen DLHP-Dokumenten kollidieren. Am
  einfachsten wird dieses dadurch erreicht, da jedes Label mit dem
  Dateinamen des Dokumentes beginnt. Das kann dann z.B. so aussehen:



       <sect2>Ein interessanter Abschnitt
              <label id="DE-Autor-HOWTO-label1">
       <p>




  Wie an diesem Beispiel sehr schn sehen kann, wird man <label> in der
  Regel direkt nach einem <sect?> Befehl benutzen. Der Befehl, mit der
  man sich dann auf diese Marke bezieht, sieht dann z.B. so aus:



       ... wie auch in Abschnitt
       <ref id="DE-Autor-HOWTO-label1"
            name="Ein interessanter Abschnitt">
       erklrt wurde.




  Das name-Argument enthlt in der Regel die berschrift des
  Abschnittes, auf den man sich bezieht.



  3.8.  Indexbefehle


  Die Befehle zur Erstellung eines Indexes <idx>, <cdx>, <nidx> und
  <ncdx> sollten nur in Absprache mit dem Herausgeber verwendet werden.
  In den meisten Fllen brauchen Sie sich um diese Befehle garnicht
  kmmern, da der Herausgeber Ihrem Dokument an sinnvollen Stellen diese
  Befehle hinzufgen wird, wenn das Dokument verffentlicht wird.


  3.9.  Anfhrungszeichen


  Im Gegensatz zu den englischen HOWTOs werden die franzsischen
  Anfhrungszeichen  verwendet. Diese knnen unter Linux direkt ber
  die Tastatur mittels AltGr-x und AltGr-y eingegeben werden.  Auf
  anderen Systemen knnen die Anfhrungszeichen als &raquo; und &laquo;
  eingegeben werden.






  3.10.  Fachbegriffe bersetzen?


  Fachbegriffe sollten nur dann bersetzt werden, wenn eine deutsche
  bersetzung existiert, die sich wirklich durchgesetzt hat. So kann
  z.B. user gut mit Benutzer oder floppy mit Diskette bersetzt werden.

  Es geht jedoch auf keinen Fall darum, neue bersetzte Fachbegriffe mit
  einer bersetzung zu schaffen! Als Leser mchte ich nicht zuerst jeden
  Fachbegriff ins Englische zurckbersetzen, um zu verstehen, was
  berhaupt gemeint war. Sowas wie Laufzeitbinder fr linker oder
  Kellerspeicher fr stack sollte auf keinen Fall verwendet werden.


  3.11.  Rechtschreibung


  Nach Mglichkeit sollte die alte Rechtschreibung verwendet werden,
  so da dem Leser der HOWTOs nicht zwei verschiedene Schreibweisen
  zugemutet werden.


  3.12.  Schreibweise spezieller Wrter


  Es folgt eine kleine Liste der Schreibweise einiger Wrter. Wenn Sie
  weitere Wrter haben, schicken Sie mir diese bitte. Die Schreibweise
  sollte in allen HOWTOs gleich sein.


     C  CD-ROM-Laufwerk, Clients


     E  E-Mail


     L  LILO, Linux-Distribution


     M  Mailingliste, Manual Page


     N  Newsgruppe


     S  Skript




















