Johann
Kois
Übersetzt von
Der Schreibstil
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.
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 &man.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.
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.
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…>.
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.
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ü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.
...
]]>
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
Die korrekte Schreibweise von Tags
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:
NIS
October 1999
...
...
...
...
...
...
...
]]>
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.
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.
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
verhindert Zeilenumbrüche zwischen zusammengehörenden
Teilen. Verwenden Sie non-breaking
spaces daher in den folgenden Fällen:
Zwischen Zahlen und Einheiten:
Zwischen Programmnamen und Versionsnummern:
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
):
Häufig verwendete Wörter
Die folgende Liste enthält einige Beispiele, wie
bestimmte Wörter innerhalb des FreeBSD
Documentation Projects geschrieben werden. Finden Sie ein
gesuchtes Wort hier nicht, sehen Sie bitte in der
Liste häufig verwendeter Wörter von
O'Reilly nach.
2.2.X
4.X-STABLE
CD-ROM
DoS (Denial of Service)
Ports Collection
IPsec
Internet
MHz
Soft Updates
Unix
disk label
email
file system
manual page
mail server
name server
null-modem
web server