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

ftp://sunsite.unc.edu/pub

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://www.linuxdoc.org/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 Herausgeber verwendet werden. In den meisten Fällen brauchen Sie sich um diese Befehle garnicht kümmern, da der Herausgeber 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, Clients

E

E-Mail

L

LILO, Linux-Distribution

M

Mailingliste, Manual Page

N

Newsgruppe

S

Skript

Hosting by: Hurra Communications GmbH
Generated: 2007-01-26 17:56:56