<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
$FreeBSDde$
basiert auf: r38872
-->
<chapter id="writing-style">
<chapterinfo>
<authorgroup>
<author>
<firstname>Johann</firstname>
<surname>Kois</surname>
<contrib>�bersetzt von </contrib>
</author>
</authorgroup>
</chapterinfo>
<title>Der Schreibstil</title>
<para>Damit von verschiedenen Autoren geschriebene Dokumente
zueinander konsistent bleiben, gibt es einige Richtlinien, denen
Autoren bei der Erstellung ihrer Dokumente folgen m�ssen.</para>
<variablelist>
<varlistentry>
<term>Verwendung von amerikanischem Englisch</term>
<listitem>
<para>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 <quote>color</quote> statt
<quote>colour</quote>, <quote>rationalize</quote> statt
<quote>rationalise</quote>, und so weiter.</para>
<note>
<para>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.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>Vermeiden von Zusammenziehungen</term>
<listitem>
<para>Verwenden Sie keine Zusammenziehungen, sondern schreiben
Sie die Phrase immer aus. Die Schreibweise
<quote>Don't use contractions.</quote> w�re also nicht
korrekt.</para>
<para>Die Vermeidung von Zusammenziehungen sorgt f�r einen
etwas formelleren Ton, ist pr�ziser und erleichtert die
Arbeit der �bersetzer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Nutzung von Kommas bei Aufz�hlungen</term>
<listitem>
<para>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 <quote>und</quote>.</para>
<para>Dazu ein Beispiel:</para>
<blockquote>
<para>Das ist eine Liste von ein, zwei und drei Dingen.</para>
</blockquote>
<para>Handelt es sich dabei um eine Liste von drei Begriffen,
<quote>ein</quote>, <quote>zwei</quote>, und
<quote>drei</quote>, oder um eine Liste von zwei Begriffen,
<quote>ein</quote> und <quote>zwei und drei</quote>?</para>
<para>Es ist daher besser, explizit ein serielles Komma zu
setzen:</para>
<blockquote>
<para>Das ist eine Liste von ein, zwei, und drei Dingen.</para>
</blockquote>
</listitem>
</varlistentry>
<varlistentry>
<term>Vermeidung von redundanten Begriffen</term>
<listitem>
<para>Versuchen Sie, keine redundanten Phrasen zu verwenden.
Dies gilt insbesondere f�r die Ausdr�cke
<quote>der Befehl</quote>, <quote>die Datei</quote>, und
<quote>man command</quote>.</para>
<para>Die folgenden zwei Beispiele veranschaulichen dies
f�r Befehle. Bevorzugt wird die Schreibweise des
zweiten Beispiels.</para>
<informalexample>
<para>Verwenden Sie den Befehl <command>cvsup</command>, um
Ihre Quellen zu aktualisieren.</para>
</informalexample>
<informalexample>
<para>Verwenden Sie <command>cvsup</command>, um Ihre Quellen
zu aktualisieren.</para>
</informalexample>
<para>Analoges gilt f�r Dateinamen, wobei wiederum die
zweite Schreibweise bevorzugt wird.</para>
<informalexample>
<para>… in der Datei
<filename>/etc/rc.local</filename>…</para>
</informalexample>
<informalexample>
<para>… in
<filename>/etc/rc.local</filename>…</para>
</informalexample>
<para>Auch f�r Manualpages gibt es zwei Schreibweisen.
Auch hier wird die zweite Schreibweise bevorzugt (das
zweite Beispiel nutzt das Tag
<sgmltag>citerefentry</sgmltag>).</para>
<informalexample>
<para>Weitere Informationen finden Sie in
<command>man csh</command>.</para>
</informalexample>
<informalexample>
<para>Weitere Informationen finden Sie in &man.csh.1;.</para>
</informalexample>
</listitem>
</varlistentry>
<varlistentry>
<term>Zwei Leerzeichen am Satzende</term>
<listitem>
<para>Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes.
Dadurch erh�ht sich die Lesbarkeit des Textes und die
Nutzung von Werkzeugen wie <application>Emacs</application>
wird vereinfacht.</para>
<para>Nun k�nnte man behaupten, dass ein Punkt vor einem
Gro�buchstaben das Satzende markiert. Vor allem bei
Namen, beispielsweise bei <quote>Jordan K. Hubbard</quote>,
ist dies allerdings nicht der Fall. Wir haben hier ein
gro�es <literal>K</literal>, gefolgt von einem Punkt
und einem Leerzeichen. Dennoch handelt es sich nicht um
den Anfang eines neuen Satzes.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Eine ausf�hrliche Beschreibung des korrekten Schreibstils
finden Sie im Buch <ulink url="http://www.bartleby.com/141/">Elements
of Style</ulink> von William Strunk.</para>
<sect1 id="writing-style-guide">
<title>Anleitungen f�r einen korrekten Schreibstil</title>
<para>Damit die Quellen der Dokumentation selbst dann konsistent
bleiben, wenn viele Leute daran arbeiten, folgen Sie bitte den
folgenden Konventionen.</para>
<sect2>
<title>Gro�- und Kleinschreibung</title>
<para>Tags werden in Kleinbuchstaben geschrieben, Sie schreiben
also <sgmltag>para</sgmltag>, <emphasis>nicht</emphasis>
<sgmltag>PARA</sgmltag>.</para>
<para>Text im SGML-Kontext wird hingegen in Gro�buchstaben
geschrieben. Man schreibt also
<literal><!ENTITY…></literal> und
<literal><!DOCTYPE…></literal>,
<emphasis>nicht</emphasis>
<literal><!entity…></literal> und
<literal><!doctype…></literal>.</para>
</sect2>
<sect2>
<title>Abk�rzungen (Akronyme)</title>
<para>Abk�rzungen sollten bei ihrer ersten Verwendung immer
ausgeschrieben werden. Man schreibt also beispielsweise
<quote>Network Time Protocol (<acronym
role="Network Time Protocol">NTP</acronym>)</quote>. 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.</para>
<para>Die drei ersten Vorkommen der Abk�rzung sollten in
<sgmltag>acronym</sgmltag>-Tags eingeschlossen werden.
Zus�tzlich wird ein <literal>role</literal>-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.</para>
</sect2>
<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>
<para>�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.</para>
<para>Der Quellcode dieses Abschnitts sieht daher in etwa so
aus:</para>
<programlisting><![CDATA[+--- 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>]]></programlisting>
<para>Wenn Sie <application>Emacs</application> oder
<application>XEmacs</application> verwenden, um Ihre Dateien zu
bearbeiten, sollte der <literal>sgml-mode</literal> automatisch
geladen werden, und die lokalen
<application>Emacs</application>-Variablen am Ende einer Datei
sollten diesen Stil erzwingen.</para>
<para>Verwenden Sie <application>Vim</application>, sollten Sie
Ihren Editor so konfigurieren:</para>
<programlisting>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</programlisting>
</sect2>
<sect2>
<title>Die korrekte Schreibweise von Tags</title>
<sect3>
<title>Einr�cken von Tags</title>
<para>Tags, die die gleiche Einr�ckung aufweisen wie das
vorangegangene Tag, sollten durch eine Leerzeile getrennt
werden, Tags mit unterschiedlicher Einr�ckung hingegen
nicht:</para>
<informalexample>
<programlisting><![CDATA[<article lang='de'>
<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>]]></programlisting>
</informalexample>
</sect3>
<sect3>
<title>Gliederung von Tags</title>
<para>Tags wie zum Beispiel <sgmltag>itemizedlist</sgmltag>, die
immer weitere Tags einschlie�en und selbst keine Zeichen
enthalten, befinden sich immer in einer eigenen Zeile.</para>
<para>Tags wie <sgmltag>para</sgmltag> und
<sgmltag>term</sgmltag> k�nnen selbst Text enthalten,
und ihr Inhalt beginnt direkt nach dem Tag, und zwar
<emphasis>in der gleichen Zeile</emphasis>.</para>
<para>Dies gilt analog, wenn diese zwei Tag-Arten wieder
geschlossen werden.</para>
<para>Eine Vermischung dieser Tags kann daher zu Problemen
f�hren.</para>
<para>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.</para>
<para>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.</para>
</sect3>
</sect2>
<sect2>
<title>Markup-�nderungen (<foreignphrase>white space
changes</foreignphrase>)</title>
<para>Wenn Sie �nderungen committen, <emphasis>committen Sie
niemals Inhalts- und Formatierungs�nderungen zur gleichen
Zeit</emphasis>.</para>
<para>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.</para>
<para>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 (<foreignphrase>whitespace-only
change</foreignphrase>), und �bersetzer den Commit daher
ignorieren k�nnen.</para>
</sect2>
<sect2>
<title>Vermeiden von fehlerhaften Zeilenumbr�chen
(Nutzung von <foreignphrase>non-breaking space</foreignphrase>)</title>
<para>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:</para>
<literallayout class="monospaced">Data capacity ranges from 40 MB to 15
GB. Hardware compression …</literallayout>
<para>Die Nutzung der Entity <literal>&nbsp;</literal>
verhindert Zeilenumbr�che zwischen zusammengeh�renden
Teilen. Verwenden Sie <foreignphrase>non-breaking
spaces</foreignphrase> daher in den folgenden F�llen:</para>
<itemizedlist>
<listitem>
<para>Zwischen Zahlen und Einheiten:</para>
<programlisting><![CDATA[57600 bps]]></programlisting>
</listitem>
<listitem>
<para>Zwischen Programmnamen und Versionsnummern:</para>
<programlisting><![CDATA[FreeBSD 4.7]]></programlisting>
</listitem>
<listitem>
<para>Zwischen mehreren zusammengeh�renden W�rtern
(Vorsicht bei Namen, die aus mehr als 3-4 W�rtern
bestehen, wie <quote>The FreeBSD Brazilian Portuguese
Documentation Project</quote>):</para>
<programlisting><![CDATA[Sun Microsystems]]></programlisting>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="writing-style-word-list">
<title>H�ufig verwendete W�rter</title>
<para>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 <ulink
url="http://www.oreilly.com/oreilly/author/stylesheet.html">
Liste h�ufig verwendeter W�rter von
O'Reilly</ulink> nach.</para>
<itemizedlist>
<listitem>
<para>2.2.X</para>
</listitem>
<listitem>
<para>4.X-STABLE</para>
</listitem>
<listitem>
<para>CD-ROM</para>
</listitem>
<listitem>
<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
</listitem>
<listitem>
<para>Ports Collection</para>
</listitem>
<listitem>
<para>IPsec</para>
</listitem>
<listitem>
<para>Internet</para>
</listitem>
<listitem>
<para>MHz</para>
</listitem>
<listitem>
<para>Soft Updates</para>
</listitem>
<listitem>
<para>Unix</para>
</listitem>
<listitem>
<para>disk label</para>
</listitem>
<listitem>
<para>email</para>
</listitem>
<listitem>
<para>file system</para>
</listitem>
<listitem>
<para>manual page</para>
</listitem>
<listitem>
<para>mail server</para>
</listitem>
<listitem>
<para>name server</para>
</listitem>
<listitem>
<para>null-modem</para>
</listitem>
<listitem>
<para>web server</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>