524 lines
16 KiB
XML
524 lines
16 KiB
XML
<?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>
|