path: root/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml

<?xml version="1.0" encoding="ISO8859-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>&Uuml;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&uuml;ssen.</para>

  <variablelist>
    <varlistentry>
      <term>Verwendung von amerikanischem Englisch</term>

      <listitem>
	<para>Es gibt mehrere englische Varianten und damit verbunden
	  verschiedene Schreibweisen f&uuml;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&uuml;cher, Internetseiten,
	    Manualpages und andere m&uuml;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&auml;re also nicht
	  korrekt.</para>

	<para>Die Vermeidung von Zusammenziehungen sorgt f&uuml;r einen
	  etwas formelleren Ton, ist pr&auml;ziser und erleichtert die
	  Arbeit der &Uuml;bersetzer.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Nutzung von Kommas bei Aufz&auml;hlungen</term>

      <listitem>
	<para>Bei einer Aufz&auml;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&uuml;r die Ausdr&uuml;cke
	  <quote>der Befehl</quote>, <quote>die Datei</quote>, und
	  <quote>man command</quote>.</para>

	<para>Die folgenden zwei Beispiele veranschaulichen dies
	  f&uuml;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&uuml;r Dateinamen, wobei wiederum die
	  zweite Schreibweise bevorzugt wird.</para>

	<informalexample>
	  <para>&hellip; in der Datei
	    <filename>/etc/rc.local</filename>&hellip;</para>
	</informalexample>

	<informalexample>
	  <para>&hellip; in
	    <filename>/etc/rc.local</filename>&hellip;</para>
	</informalexample>

	<para>Auch f&uuml;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&ouml;ht sich die Lesbarkeit des Textes und die
	  Nutzung von Werkzeugen wie <application>Emacs</application>
	  wird vereinfacht.</para>

	<para>Nun k&ouml;nnte man behaupten, dass ein Punkt vor einem
	  Gro&szlig;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&szlig;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&uuml;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&uuml;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&szlig;- 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&szlig;buchstaben
	geschrieben.  Man schreibt also
	<literal>&lt;!ENTITY&hellip;&gt;</literal> und
	<literal>&lt;!DOCTYPE&hellip;&gt;</literal>,
	<emphasis>nicht</emphasis>
	<literal>&lt;!entity&hellip;&gt;</literal> und
	<literal>&lt;!doctype&hellip;&gt;</literal>.</para>
    </sect2>

    <sect2>
      <title>Abk&uuml;rzungen (Akronyme)</title>

      <para>Abk&uuml;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&uuml;rzung definiert wurde, sollte hingegen nur noch die
	Abk&uuml;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&ouml;glich, sie f&uuml;r jedes Kapitel
	erneut zu definieren.</para>

      <para>Die drei ersten Vorkommen der Abk&uuml;rzung sollten in
	<sgmltag>acronym</sgmltag>-Tags eingeschlossen werden.
	Zus&auml;tzlich wird ein <literal>role</literal>-Attribut mit dem
	vollst&auml;ndigen Begriff definiert.  Dadurch kann ein Link
	zu einem Glossar erzeugt werden.  Au&szlig;erdem wird der
	komplette Begriff angezeigt, wenn man den Mauscursor &uuml;ber
	die Abk&uuml;rzung bewegt.</para>
    </sect2>

    <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>

      <para>&Ouml;ffnende Tags erh&ouml;hen die Einr&uuml;ckung um zwei
	Leerzeichen.  Schlie&szlig;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&uuml;hrende Leerzeichen sind hier also
	nicht erlaubt.  Vermeiden Sie au&szlig;erdem Leerzeichen am
	Zeilenende.  Der Inhalt von Elementen wird um zwei Leerzeichen
	einger&uuml;ckt, wenn er sich &uuml;ber mehr als eine Zeile
	erstreckt.</para>

      <para>Der Quellcode dieses Abschnitts sieht daher in etwa so
	aus:</para>

      <programlisting><![CDATA[+--- 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>]]></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&uuml;cken von Tags</title>

	<para>Tags, die die gleiche Einr&uuml;ckung aufweisen wie das
	  vorangegangene Tag, sollten durch eine Leerzeile getrennt
	  werden, Tags mit unterschiedlicher Einr&uuml;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&szlig;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&ouml;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&uuml;hren.</para>

	<para>Wenn auf ein Start-Tag, das keine Zeichen enthalten kann,
	  unmittelbar ein Tag folgt, das andere Tags einschlie&szlig;en
	  muss, um Zeichen darzustellen, befinden sich diese Tags auf
	  verschiedenen Zeilen.  Das zweite Tag wird dabei
	  entsprechend einger&uuml;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-&Auml;nderungen (<foreignphrase>white space
        changes</foreignphrase>)</title>

      <para>Wenn Sie &Auml;nderungen committen, <emphasis>committen Sie
	niemals Inhalts- und Formatierungs&auml;nderungen zur gleichen
	Zeit</emphasis>.</para>

      <para>Nur auf diese Weise k&ouml;nnen die &Uuml;bersetzungs-Teams
	sofort erkennen, welche &Auml;nderungen durch Ihren Commit
	verursacht wurden, ohne dar&uuml;ber nachdenken zu m&uuml;ssen,
	ob sich der Inhalt einer Zeile oder nur deren Formatierung
	ge&auml;ndert hat.</para>

      <para>Nehmen wir an, Sie haben zwei S&auml;tze in einen Absatz
	eingef&uuml;gt.  Daher sind zwei Zeilen nun l&auml;nger als
	80&nbsp;Zeichen.  Zuerst committen Sie Ihre inhaltliche
	&Auml;nderung inklusive der zu langen Zeilen.  Im n&auml;chsten
	Commit korrigieren Sie den Zeilenumbruch und geben in der
	Commit-Mitteilung an, dass es sich nur um &Auml;nderung am
	Markup handelt (<foreignphrase>whitespace-only
	change</foreignphrase>), und &Uuml;bersetzer den Commit daher
	ignorieren k&ouml;nnen.</para>
    </sect2>

    <sect2>
      <title>Vermeiden von fehlerhaften Zeilenumbr&uuml;chen
        (Nutzung von <foreignphrase>non-breaking space</foreignphrase>)</title>

      <para>Vermeiden Sie Zeilenumbr&uuml;che an Stellen, an denen diese
	h&auml;sslich aussehen oder es erschweren, einem Satz zu
	folgen.  Zeilenumbr&uuml;che h&auml;ngen von der Breite des
	gew&auml;hlten Ausgabemedium ab.  Insbesondere bei der Verwendung
	von Textbrowsern k&ouml;nnen schlecht formatierte Abs&auml;tze
	wie der folgende entstehen:</para>

      <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
GB.  Hardware compression &hellip;</literallayout>

      <para>Die Nutzung der Entity <literal>&amp;nbsp;</literal>
	verhindert Zeilenumbr&uuml;che zwischen zusammengeh&ouml;renden
	Teilen.  Verwenden Sie <foreignphrase>non-breaking
	spaces</foreignphrase> daher in den folgenden F&auml;llen:</para>

      <itemizedlist>
	<listitem>
	  <para>Zwischen Zahlen und Einheiten:</para>
	  <programlisting><![CDATA[57600&nbsp;bps]]></programlisting>
	</listitem>

	<listitem>
	  <para>Zwischen Programmnamen und Versionsnummern:</para>
	  <programlisting><![CDATA[FreeBSD&nbsp;4.7]]></programlisting>
	</listitem>

	<listitem>
	  <para>Zwischen mehreren zusammengeh&ouml;renden W&ouml;rtern
	    (Vorsicht bei Namen, die aus mehr als 3-4 W&ouml;rtern
	    bestehen, wie <quote>The FreeBSD Brazilian Portuguese
	    Documentation Project</quote>):</para>
	  <programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="writing-style-word-list">
    <title>H&auml;ufig verwendete W&ouml;rter</title>

    <para>Die folgende Liste enth&auml;lt einige Beispiele, wie
      bestimmte W&ouml;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&auml;ufig verwendeter W&ouml;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>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->