Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts
Zurück |  | Weiter

# Kapitel 10. Der Schreibstil

Übersetzt von Johann Kois.

Damit von verschiedenen Autoren geschriebene Dokumente zueinander konsistent bleiben, gibt es einige Richtlinien, denen Autoren bei der Erstellung ihrer Dokumente folgen müssen.

Verwendung von amerikanischem Englisch

  Es gibt mehrere englische Varianten und damit verbunden verschiedene Schreibweisen für das gleiche Wort. Wo dies der Fall ist, ist die amerikanische Schreibweise zu verwenden. Man schreibt daher color statt colour, rationalize statt rationalise, und so weiter.

  > Anmerkung: Die Verwendung von Britischem Englisch ist akzeptabel, wenn es sich um einen neuen Beitrag handelt, solange die gesamte Schreibweise eines Dokuments einheitlich bleibt. Alle anderen Dokumente wie Bücher, Internetseiten, Manualpages und andere müssen allerdings amerikanisches Englisch verwenden.

Vermeiden von Zusammenziehungen

  Verwenden Sie keine Zusammenziehungen, sondern schreiben Sie die Phrase immer aus. Die Schreibweise Don't use contractions. wäre also nicht korrekt.

  Die Vermeidung von Zusammenziehungen sorgt für einen etwas formelleren Ton, ist präziser und erleichtert die Arbeit der Übersetzer.

Nutzung von Kommas bei Aufzählungen

  Bei einer Aufzählung innerhalb eines Absatzes sollten Sie zwischen den einzelnen Begriffen Kommas setzen. Zwischen dem letzten und vorletzten Begriff setzen Sie ein Komma und das Wort und.

  Dazu ein Beispiel:

  > Das ist eine Liste von ein, zwei und drei Dingen.

  Handelt es sich dabei um eine Liste von drei Begriffen, ein, zwei, und drei, oder um eine Liste von zwei Begriffen, ein und zwei und drei?

  Es ist daher besser, explizit ein serielles Komma zu setzen:

  > Das ist eine Liste von ein, zwei, und drei Dingen.

Vermeidung von redundanten Begriffen

  Versuchen Sie, keine redundanten Phrasen zu verwenden. Dies gilt insbesondere für die Ausdrücke der Befehl, die Datei, und man command.

  Die folgenden zwei Beispiele veranschaulichen dies für Befehle. Bevorzugt wird die Schreibweise des zweiten Beispiels.

  Verwenden Sie den Befehl `cvsup`, um Ihre Quellen zu aktualisieren.

  Verwenden Sie `cvsup`, um Ihre Quellen zu aktualisieren.

  Analoges gilt für Dateinamen, wobei wiederum die zweite Schreibweise bevorzugt wird.

  ... in der Datei `/etc/rc.local`...

  ... in `/etc/rc.local`...

  Auch für Manualpages gibt es zwei Schreibweisen. Auch hier wird die zweite Schreibweise bevorzugt (das zweite Beispiel nutzt das Tag `<citerefentry>`).

  Weitere Informationen finden Sie in `man csh`.

  Weitere Informationen finden Sie in csh(1).

Zwei Leerzeichen am Satzende

  Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes. Dadurch erhöht sich die Lesbarkeit des Textes und die Nutzung von Werkzeugen wie Emacs wird vereinfacht.

  Nun könnte man behaupten, dass ein Punkt vor einem Großbuchstaben das Satzende markiert. Vor allem bei Namen, beispielsweise bei Jordan K. Hubbard, ist dies allerdings nicht der Fall. Wir haben hier ein großes `K`, gefolgt von einem Punkt und einem Leerzeichen. Dennoch handelt es sich nicht um den Anfang eines neuen Satzes.

Eine ausführliche Beschreibung des korrekten Schreibstils finden Sie im Buch Elements of Style von William Strunk.

# 10.1. Anleitungen für einen korrekten Schreibstil

Damit die Quellen der Dokumentation selbst dann konsistent bleiben, wenn viele Leute daran arbeiten, folgen Sie bitte den folgenden Konventionen.

## 10.1.1. Groß- und Kleinschreibung

Tags werden in Kleinbuchstaben geschrieben, Sie schreiben also `<para>`, nicht `<PARA>`.

Text im SGML-Kontext wird hingegen in Großbuchstaben geschrieben. Man schreibt also `<!ENTITY...>` und `<!DOCTYPE...>`, nicht `<!entity...>` und `<!doctype...>`.

## 10.1.2. Abkürzungen (Akronyme)

Abkürzungen sollten bei ihrer ersten Verwendung immer ausgeschrieben werden. Man schreibt also beispielsweise Network Time Protocol (NTP). Nachdem die Abkürzung definiert wurde, sollte hingegen nur noch die Abkürzung verwendet werden, es sei denn, die Verwendung des gesamten Begriffes ergibt im jeweiligen Kontext mehr Sinn. Im Normalfall werden Akronyme in jedem Dokument nur einmal definiert. Es ist allerdings auch möglich, sie für jedes Kapitel erneut zu definieren.

Die drei ersten Vorkommen der Abkürzung sollten in `<acronym>`-Tags eingeschlossen werden. Zusätzlich wird ein `role`-Attribut mit dem vollständigen Begriff definiert. Dadurch kann ein Link zu einem Glossar erzeugt werden. Außerdem wird der komplette Begriff angezeigt, wenn man den Mauscursor über die Abkürzung bewegt.

## 10.1.3. Einrückung

Die erste Zeile jeder Datei hat die Einrückung 0, und zwar unabhängig von der Einrückung der Datei, in der sie enthalten ist.

Öffnende Tags erhöhen die Einrückung um zwei Leerzeichen. Schließende Tags verringern sie hingegen um zwei Leerzeichen. Ein Block von acht Leerzeichen wird durch einen Tabulator ersetzt. Ein solcher Block beginnt immer am Anfang einer Zeile, führende Leerzeichen sind hier also nicht erlaubt. Vermeiden Sie außerdem Leerzeichen am Zeilenende. Der Inhalt von Elementen wird um zwei Leerzeichen eingerückt, wenn er sich über mehr als eine Zeile erstreckt.

Der Quellcode dieses Abschnitts sieht daher in etwa so aus:

    +--- Einr&uuml;ckung (Spalte) 0
    V
    <chapter>
      <title>...</title>

      <sect1>
        <title>...</title>

        <sect2>
          <title>Einr&uuml;ckung</title>

          <para>Die erste Zeile jeder Datei hat die Einr&uuml;ckung 0, und
            zwar <emphasis>unabh&auml;ngig</emphasis> von der Einr&uuml;ckung
            der Datei, in der sie enthalten ist.</para>

          ...
        </sect2>
      </sect1>
    </chapter>

Wenn Sie Emacs oder XEmacs verwenden, um Ihre Dateien zu bearbeiten, sollte der `sgml-mode` automatisch geladen werden, und die lokalen Emacs-Variablen am Ende einer Datei sollten diesen Stil erzwingen.

Verwenden Sie Vim, sollten Sie Ihren Editor so konfigurieren:

    augroup sgmledit
      autocmd FileType sgml set formatoptions=cq2l " Special formatting options
      autocmd FileType sgml set textwidth=70       " Wrap lines at 70 columns
      autocmd FileType sgml set shiftwidth=2       " Automatically indent
      autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
      autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
      autocmd FileType sgml set autoindent         " Automatic indentation
    augroup END

## 10.1.4. Die korrekte Schreibweise von Tags

### 10.1.4.1. Einrücken von Tags

Tags, die die gleiche Einrückung aufweisen wie das vorangegangene Tag, sollten durch eine Leerzeile getrennt werden, Tags mit unterschiedlicher Einrückung hingegen nicht:

    <article>
      <articleinfo>
        <title>NIS</title>

        <pubdate>October 1999</pubdate>

        <abstract>
          <para>...
    	...
    	...</para>
        </abstract>
      </articleinfo>

      <sect1>
        <title>...</title>

        <para>...</para>
      </sect1>

      <sect1>
        <title>...</title>

        <para>...</para>
      </sect1>
    </article>

### 10.1.4.2. Gliederung von Tags

Tags wie zum Beispiel `<itemizedlist>`, die immer weitere Tags einschließen und selbst keine Zeichen enthalten, befinden sich immer in einer eigenen Zeile.

Tags wie `<para>` und `<term>` können selbst Text enthalten, und ihr Inhalt beginnt direkt nach dem Tag, und zwar in der gleichen Zeile.

Dies gilt analog, wenn diese zwei Tag-Arten wieder geschlossen werden.

Eine Vermischung dieser Tags kann daher zu Problemen führen.

Wenn auf ein Start-Tag, das keine Zeichen enthalten kann, unmittelbar ein Tag folgt, das andere Tags einschließen muss, um Zeichen darzustellen, befinden sich diese Tags auf verschiedenen Zeilen. Das zweite Tag wird dabei entsprechend eingerückt.

Wenn ein Tag, das Zeichen enthalten kann, direkt nach einem Tag, das keine Zeichen enthalten kann, geschlossen wird, befinden sich beide Tags in der gleichen Zeile.

## 10.1.5. Markup-Änderungen (white space changes)

Wenn Sie Änderungen committen, committen Sie niemals Inhalts- und Formatierungsänderungen zur gleichen Zeit.

Nur auf diese Weise können die Übersetzungs-Teams sofort erkennen, welche Änderungen durch Ihren Commit verursacht wurden, ohne darüber nachdenken zu müssen, ob sich der Inhalt einer Zeile oder nur deren Formatierung geändert hat.

Nehmen wir an, Sie haben zwei Sätze in einen Absatz eingefügt. Daher sind zwei Zeilen nun länger als 80 Zeichen. Zuerst committen Sie Ihre inhaltliche Änderung inklusive der zu langen Zeilen. Im nächsten Commit korrigieren Sie den Zeilenumbruch und geben in der Commit-Mitteilung an, dass es sich nur um Änderung am Markup handelt (whitespace-only change), und Übersetzer den Commit daher ignorieren können.

## 10.1.6. Vermeiden von fehlerhaften Zeilenumbrüchen (Nutzung von non-breaking space)

Vermeiden Sie Zeilenumbrüche an Stellen, an denen diese hässlich aussehen oder es erschweren, einem Satz zu folgen. Zeilenumbrüche hängen von der Breite des gewählten Ausgabemedium ab. Insbesondere bei der Verwendung von Textbrowsern können schlecht formatierte Absätze wie der folgende entstehen:

    Data capacity ranges from 40 MB to 15
    GB.  Hardware compression ...

Die Nutzung der Entity `&nbsp;` verhindert Zeilenumbrüche zwischen zusammengehörenden Teilen. Verwenden Sie non-breaking spaces daher in den folgenden Fällen:

- Zwischen Zahlen und Einheiten:

      57600&nbsp;bps

- Zwischen Programmnamen und Versionsnummern:

      FreeBSD&nbsp;4.7

- Zwischen mehreren zusammengehörenden Wörtern (Vorsicht bei Namen, die aus mehr als 3-4 Wörtern bestehen, wie The FreeBSD Brazilian Portuguese Documentation Project):

      Sun&nbsp;Microsystems

Zurück | Zum Anfang | Weiter
Übersetzungen |  | Häufig verwendete Wörter

Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an <de-bsd-questions@de.FreeBSD.org>.
Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail an <de-bsd-translators@de.FreeBSD.org>.