diff options
Diffstat (limited to 'de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.xml')
| -rw-r--r-- | de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.xml | 517 |
1 files changed, 0 insertions, 517 deletions
diff --git a/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.xml deleted file mode 100644 index 55d6280308..0000000000 --- a/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ /dev/null @@ -1,517 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- 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: r40542 ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style"> - <info><title>Der Schreibstil</title> - <authorgroup> - <author><personname><firstname>Johann</firstname><surname>Kois</surname></personname><contrib>Übersetzt von </contrib></author> - </authorgroup> - </info> - - - - <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>svn</command>, um - Ihre Quellen zu aktualisieren.</para> - </informalexample> - - <informalexample> - <para>Verwenden Sie <command>svn</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 - <tag>citerefentry</tag>).</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 <link xlink:href="http://www.bartleby.com/141/">Elements - of Style</link> von William Strunk.</para> - - <sect1 xml: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 <tag>para</tag>, <emphasis>nicht</emphasis> - <tag>PARA</tag>.</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 - <tag>acronym</tag>-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 <tag>itemizedlist</tag>, die - immer weitere Tags einschließen und selbst keine Zeichen - enthalten, befinden sich immer in einer eigenen Zeile.</para> - - <para>Tags wie <tag>para</tag> und - <tag>term</tag> 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 xml: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 <link xlink:href="http://www.oreilly.com/oreilly/author/stylesheet.html"> - Liste häufig verwendeter Wörter von - O'Reilly</link> 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> |