Damit von verschiedenen Autoren geschriebene Dokumente zueinander konsistent bleiben, gibt es einige Richtlinien, denen Autoren bei der Erstellung ihrer Dokumente folgen müssen.
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.
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.
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.
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.
Analoges gilt für Dateinamen, wobei wiederum die zweite Schreibweise bevorzugt wird.
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 csh(1).
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.
Damit die Quellen der Dokumentation selbst dann konsistent bleiben, wenn viele Leute daran arbeiten, folgen Sie bitte den folgenden Konventionen.
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…>.
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.
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ückung (Spalte) 0
V
<chapter>
<title>...</title>
<sect1>
<title>...</title>
<sect2>
<title>Einrückung</title>
<para>Die erste Zeile jeder Datei hat die Einrückung 0, und
zwar <emphasis>unabhängig</emphasis> von der Einrü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
Tags, die die gleiche Einrückung aufweisen wie das vorangegangene Tag, sollten durch eine Leerzeile getrennt werden, Tags mit unterschiedlicher Einrückung hingegen nicht:
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.
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.
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 verhindert Zeilenumbrüche zwischen zusammengehörenden Teilen. Verwenden Sie non-breaking spaces daher in den folgenden Fällen:
Zwischen Zahlen und Einheiten:
57600 bps
Zwischen Programmnamen und Versionsnummern:
FreeBSD 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 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>.