DLHP Autor HOWTO Marco Budde (Budde@tu-harburg.de) v1.6-2, 20. Mai 2000 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 möchte. Es wird beschrieben, wie eine HOWTO genau formatiert werden sollte. Dieses ist wichtig, damit alle deutschen HOWTOs ähnlich aussehen und den gleichen Qualitätsansprüchen genügen. Falls Sie der Meinung sind, daß man einige der hier beschriebenen Sachen besser machen könnte, zögern Sie bitte nicht und schicken Sie mir ein E-Mail. 1.2. Copyright Dieses Dokument ist urheberrechtlich geschützt. 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 Lizenzgebühren verbreitet werden darf, solange dieser Copyright Hinweis nicht entfernt wird. Eine kommerzielle Verbreitung ist erlaubt und ausdrücklich erwünscht. Bei einer Publikation in Papierform ist das Deutsche Linux HOWTO Projekt hierüber zu informieren. 2. Grundlagen 2.1. Wie kann ich mich am DLHP beteiligen? Wenn Sie selbst eine HOWTO übersetzen oder eine eigene schreiben möchten, erreichen Sie den Koordinator des DLHP unter: Internet: Budde@tu-harburg.de Fido: Marco Budde@2:240/6298.5 Um sicherzustellen, daß nicht eine HOWTO von mehreren Leuten bearbeitet wird, müssen Sie dem Koordinator unbedingt zuerst mitteilen, welche HOWTO Sie bearbeiten wollen, bevor Sie anfangen. Wenn Sie eine englische HOWTO übersetzen möchten, können Sie sich selbst eine aussuchen, die Sie bearbeiten möchten. Gehen Sie dabei folgendermaßen vor: 1. Suchen Sie sich eine interessante HOWTO von folgendem Server aus: metalab.unc.edu:/pub/Linux/docs/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 Koordinator die ausgesuchte HOWTO mit. Nach einiger Zeit sollte Ihre HOWTO dann auch in DE-HOWTO auftauchen. Falls dieses nicht der Fall ist, der Koordinator kann ja auch mal was vergessen :), weisen Sie den Koordinator bitte unbedingt darauf hin. 2.2. Was tun nach der Übersetzung? Fertige HOWTOs schicken Sie dem Koordinator 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 Koordinators 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 vollständig durch und überprüfen Sie, ob Sie nichts vergessen haben. Testen Sie also unbedingt vorher, ob sich Ihr Source in alle verwendeten Format ohne Fehler übersetzen läßt und ob die Formatierung der hier beschriebenen entspricht. Zum Test können Sie folgenden Makefile benutzen: http://www.tu-harburg.de/dlhp/FTP/tools/Makefile Denken Sie bitte an die Klärung des Copyrights; siehe ``Copyright der HOWTOs''. Nachdem Sie Ihre HOWTO abgeschickt habe, schreiben Sie bitte zuerst keine weiteren Updates. Der DLHP-Maintainer wird die eingehenden Versionen überprüfen und eventuelle Fehler beseitigen. Dieser Prozeß kann - gerade bei der ersten Version - einige Zeit dauern. Sie können diesen Prozeß dadurch beschleunigen, daß Sie sich von Anfang an möglichst genau an die Ratschläge in dieser HOWTO halten. Nachdem die HOWTO vom DLHP-Maintainer bearbeitet worden ist, wird sie auf unserer Homepage veröffentlicht. Benutzen Sie dann bitte den auf der Homepage gespeicherten SGML-Source Ihrer HOWTO für spätere Updates. Und schauen Sie sich mal mit diff -u die Änderungen an, die der DLHP-Maintainer an Ihrem Text vorgenommen hat. Dieses kann hilfreich sein, um die gleichen Fehler bei späteren Updates nicht wieder einzubauen. 2.3. 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 Auf keinen Fall kann die Version 2.x benutzt werden, da diese völlig inkompatibel zur alten ist und noch nicht ausgereift ist. Außerdem wurde die Entwicklung der 2.x Version anscheinend eingestellt. Speziell für das DLHP gibt es einen Patch für die sgml-tools, der hier zu finden ist: http://www.tu-harburg.de/dlhp/FTP/tools/ Diese Version enthält 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.4. Vorlagen Für die Übersetzung einer HOWTO empfiehlt es sich, den SGML Source der entsprechenden HOWTO von metalab.unc.edu:/pub/Linux/docs/howto/other-formats/sgml/ zu beziehen und als Grundlage für 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.5. Copyright der HOWTOs Wenn Sie eine englische HOWTO übersetzen, überprüfen Sie bitte das Copyright der englischen HOWTO. Die HOWTOs des DLHP sollen möglichst 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 können. Und fragen Sie den Autor wirklich und ändern Sie nicht einfach nur die Lizenz. Bei Urheberrechtsverstössen haftet der Übersetzer und nicht das DLHP! Leiten Sie bitte eine Kopie der Erlaubnis an der Koordinator weiter. Die HOWTO sollte irgendwo in der Einleitung - meistens das erste Kapitel - einen Copyright Hinweis wie den folgenden enthalten: Copyright

Dieses Dokument ist urheberrechtlich geschützt. Das Copyright für die englische verbreitet werden. Insbesondere bedeutet dieses, daß der Text sowohl über elektronische wie auch physikalische Medien ohne die Zahlung von Lizenzgebühren verbreitet werden darf, solange dieser Copyright-Hinweis nicht entfernt wird. Eine kommerzielle Verbreitung ist erlaubt und ausdrücklich erwünscht. Bei einer Publikation in Papierform ist das Deutsche Linux HOWTO Projekt hierüber zu informieren. Hierbei sollten alle Leute, die mehr als einen Satz zu dem Dokument beigetragen haben, erwähnt werden. Sollten Sie keine HOWTO übersetzen, sondern eine eigene schreiben, so verwenden Sie bitte auch die GNU GPL. Denn zu einem freien Betriebssystem gehört auch eine freie Dokumentation. 2.6. SGML Header Jedes SGML Dokument beginnt mit einem Header wie dem folgendem:

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.7. Umlaute Die Umlaute sollen in den formatierten Dokumenten in der Form »ü« und nicht in der Form »ue« erscheinen. Die sgml-tools bieten zwei Möglichkeiten, die Umlaute einzugeben: · Latin-1 Zeichensatz (8 Bit): ü · HTML Form (7 Bit): ü Wenn möglich, sollte die erste Möglichkeit gewählt werden, da man so den Source mit jedem Editor gut lesen kann. 2.8. 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 könnte, daß sich die HOWTOs nur an einen kleinen Kreis von Programmierern und Administratoren richten. 2.9. SGML-Sourcen Achten Sie bitte darauf, daß Ihr SGML-Source vernünftig lesbar ist. Dazu gehört es z.B., daß die Zeilen nach spätestens 80 Zeichen umgebrochen werden. Bei langen URLs oder ähnlichen Dinge kann natürlich eine Ausnahme gemacht werden. Fließtext wird nicht akzeptiert, da sich dieser nicht vernünftig lesen und bearbeiten läßt. Fügen 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 für Programmnamen, wenn damit die ausführbare 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 würde man also folgendes verwenden: <tscreen><htmlurl url="ftp://metalab.unc.edu/pub" name="metalab.unc.edu:/pub"></tscreen> Das <tscreen> sorgt dafür, 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 unnötiger 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, schließen 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 würde 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://metalab.unc.edu/LDP/HOWTO/PPP-HOWTO.html" name="PPP HOWTO"></em> 3.6. Listings, Kommandozeile Listings und Beispiele für 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 Zeilenlänge. 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 müssen so umformuliert werden, daß sie die Längenbeschränkung erfüllen. Hierbei ist darauf zu achten, daß die Listings bzw. Kommandos weiterhin vom Syntax her korrekt sind. Bei einem bash-Skript würde 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 natürlich 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 führt sehr schnell zu Problemen, wenn Sie weitere Abschnitte einfügen. Die sgml-tools bieten für diesen Zweck die beiden Befehle <label> und <ref>. Mit <label> markieren Sie den Abschnitt, auf den Sie sich beziehen möchten. Bei Verwendung des <label>-Befehls, sorgen Sie bitte dafür, 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 schön 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"> erklärt wurde. Das name-Argument enthält 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 Koordinator verwendet werden. In den meisten Fällen brauchen Sie sich um diese Befehle garnicht kümmern, da der Koordinator Ihrem Dokument an sinnvollen Stellen diese Befehle hinzufügen wird, wenn das Dokument veröffentlicht wird. 3.9. Anführungszeichen Im Gegensatz zu den englischen HOWTOs werden die französischen Anführungszeichen »« verwendet. Diese können unter Linux direkt über die Tastatur mittels AltGr-x und AltGr-y eingegeben werden. Auf anderen Systemen können die Anführungszeichen als » und « 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 möchte ich nicht zuerst jeden Fachbegriff ins Englische zurückübersetzen, um zu verstehen, was überhaupt gemeint war. Sowas wie Laufzeitbinder für linker oder Kellerspeicher für stack sollte auf keinen Fall verwendet werden. 3.11. Rechtschreibung Nach Möglichkeit sollte die »alte« Rechtschreibung verwendet werden, so daß dem Leser der HOWTOs nicht zwei verschiedene Schreibweisen »zugemutet« werden. 3.12. Schreibweise spezieller Wörter Es folgt eine kleine Liste der Schreibweise einiger Wörter. Wenn Sie weitere Wörter haben, schicken Sie mir diese bitte. Die Schreibweise sollte in allen HOWTOs gleich sein. C CD-ROM-Laufwerk E E-Mail L LILO, Linux-Distribution M Mailingliste, Manual Page N Newsgruppe S Skript