repo_zf1/documentation/manual/de/ref/documentation-standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: 22743 -->
<appendix id="doc-standard">
    <title>Zend Framework Dokumentations Standard</title>

    <sect1 id="doc-standard.overview">
        <title>Übersicht</title>

        <sect2 id="doc-standard.overview.scope">
            <title>Ziele</title>

            <para>
                Dieses Dokument bietet Richtlinien für die Erstellung der End-Benutzer
                Dokumentation, die im Zend Framework gefunden werden kann. Es ist als Richtlinie
                für die Mitglieder des Zend Framework gedacht, welche Dokumentationen als Teil
                ihrer übermittelten Komponenten Dokumentation schreiben müssen, sowie für die
                Übersetzer von Dokumentation. Der hier enthaltene Standard ist gedacht für einfache
                Übersetzung von Dokumentationen, minimalisieren von Visualisierung und
                stylistischen Unterschieden zwischen den unterschiedlichen Dokumentationsdateien,
                und macht das Finden von Änderungen in der Dokumentation einfacher mit
                <command>diff</command> Tools.
            </para>

            <para>
                Man kann diese Standards zusammen mit den Regeln unserer
                <ulink url="http://framework.zend.com/license">Lizenz</ulink> adoptieren und oder
                modifizieren.
            </para>

            <para>
                Themen, die im Zend Framework Dokumentations Standard beschrieben sind, enthalten die
                Formatierung von Dokumentationsdateien sowie Empfehlungen für die Qualität der
                Dokumentation.
            </para>
        </sect2>
    </sect1>

    <sect1 id="doc-standard.file-formatting">
        <title>Formatierung von Dokumentationsdateien</title>

        <sect2 id="doc-standard.file-formatting.xml-tags">
            <title>XML Tags</title>

            <para>
                Jede Datei des Manuals muss die folgenden <acronym>XML</acronym> Deklarationen am
                Beginn der Datei enthalten:
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
]]></programlisting>

            <para>
                <acronym>XML</acronym> Dateien von übersetzten Sprachen müssen auch ein Revisions
                Tag enthalten, das mit der Revision der englischen Sprachdatei korrespondiert, auf
                der die Übersetzung basiert.
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.max-line-length">
            <title>Maximale Zeilenlänge</title>

            <para>
                Die maximale Zeilenlänge, inklusive Tags, Attribute und Einrückungen, darf 100
                Zeichen nicht überschreiten. Es gibt nur eine einzige Ausnahme zu dieser Regel:
                Attributen und Werte Paaren ist es erlaubt die 100 Zeichen zu überschreiten wenn
                diese nicht getrennt werden dürfen.
            </para>
        </sect2>

        <sect2 id="doc-standard.file-formatting.indentation">
            <title>Einrückung</title>

            <para>
                Eine Einrückung sollte aus 4 Leerzeichen bestehen. Tabulatoren sind nicht erlaubt.
            </para>

            <para>
                Tags, welche auf dem gleichen Level sind, müssen auch die gleiche Einrückung haben.
            </para>

            <programlisting language="xml"><![CDATA[
<sect1>
</sect1>

<sect1>
</sect1>
]]></programlisting>

            <para>
                Tags, welche ein Level unter dem vorhergehenden Tag sind, müssen mit 4 zusätzlichen
                Leerzeichen eingerückt werden.
            </para>

            <programlisting language="xml"><![CDATA[
<sect1>
    <sect2>
    </sect2>
</sect1>
]]></programlisting>

            <para>
                Mehrere Block Tags in der gleichen Zeile sind nicht erlaubt; mehrere Inline Tags
                sind trotzdem erlaubt.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<sect1><sect2>
</sect2></sect1>

<!-- ERLAUBT -->
<para>
    <classname>Zend_Magic</classname> existiert nicht. <classname>Zend_Acl</classname> existiert.
</para>
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.line-termination">
            <title>Zeilenendekennzeichen</title>

            <para>
                Die Zeilenendekennzeichen folgt der Unix Textdatei Konvention. Zeilen müssen mit einem
                einzelnen Linefeed (LF) Zeichen enden. Linefeed Zeichen werden als ordinale 10,
                oder Hexadezimale 0x0A repräsentiert.
            </para>

            <para>
                Beachte: Es sind keine Carriage Returns (<acronym>CR</acronym>) zu verwenden, welche
                die Konvention in Apple OS's (0x0D) sind, oder die Carriage Return - Linefeed
                Kombination (<acronym>CRLF</acronym>), welche der Standard für Windows OS (0x0D,
                0x0A) sind.
            </para>
        </sect2>

        <sect2 id="doc-standard.file-formatting.empty-tags">
            <title>Leere Tags</title>

            <para>
                Leere Tags sind nicht erlaubt; alle Tags müssen Text oder Untertags enthalten.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<para>
    Irgendein Text. <link></link>
</para>

<para>
</para>
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.whitespace">
            <title>Verwendung von Leerzeichen in Dokumenten</title>

            <sect3 id="doc-standard.file-formatting.whitespace.trailing">
                <title>Leerzeichen in Tags</title>

                <para>
                    Öffnende Block Tags sollten direkt anschliessend keine Leerzeichen haben, sondern
                    nur einen Zeilenumbruch (und Einrückungen in der folgenden Zeile).
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<sect1>LEERZEICHEN
</sect1>
]]></programlisting>

                <para>
                    Öffnende Inline Tags sollten keine Leerzeichen haben, die direkt folgen.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
Das ist die Klasse <classname> Zend_Class</classname>.

<!-- OK -->
Das ist die Klasse <classname>Zend_Class</classname>.
]]></programlisting>

                <para>
                    Schließenden Block Tags können Leerzeichen vorangestellt sein, die dem aktuellen
                    Einrückungslevel entsprechen, aber nicht mehr als diese Anzahl.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
    <sect1>
     </sect1>

<!-- OK -->
    <sect1>
    </sect1>
]]></programlisting>

                <para>
                    Schließenden Inline Tags dürfen keine Leerzeichen vorangestellt sein.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
Das ist die Klasse <classname>Zend_Class </classname>

<!-- OK -->
Das ist die Klasse <classname>Zend_Class</classname>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.whitespace.multiple-line-breaks">
                <title>Mehrere Zeilenumbrüche</title>

                <para>
                    Mehrere Zeilenumbrüche innerhalb oder auch zwischen Tags sind nicht erlaubt.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<para>
    Etwas Text...

    ... und mehr Text.
</para>


<para>
    Anderer Paragraph.
</para>

<!-- OK -->
<para>
    Etwas Text...
    ... und mehr Text
</para>

<para>
    Anderer Paragraph.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.whitespace.tag-separation">
                <title>Trennung zwischen Tags</title>

                <para>
                    Tags auf dem gleichen Level müssen durch eine leere Zeile getrennt sein, um die
                    Lesbarkeit zu erhöhen.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<para>
    Etwas Text...
</para>
<para>
    Mehr Text...
</para>

<!-- OK -->
<para>
    Etwas Text...
</para>

<para>
    Mehr Text...
</para>
]]></programlisting>

                <para>
                    Das erste Untertag sollte direkt unterhalb seiner Eltern geöffnet werden, ohne
                    dass eine leere Zeile zwischen ihnen ist; das letzte Untertag sollte direkt vor
                    dem schließenden Tag seiner Eltern geschlossen werden.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<sect1>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

</sect1>

<!-- OK -->
<sect1>
    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>
</sect1>
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="doc-standard.file-formatting.program-listing">
            <title>Programmcode-Abschnitte</title>

            <para>
                Das öffnende <emphasis>&lt;programlisting&gt;</emphasis> Tag muss das richtige
                "language" Attribut anzeigen und auf dem gleichen Level eingerückt sein wie die
                vorhergehenden Blöcke.
            </para>

            <programlisting language="xml"><![CDATA[
<para>Vorhergehender Paragraph.</para>

<programlisting language="php">]]>&lt;<![CDATA[![CDATA[
]]></programlisting>

            <para>
                <acronym>CDATA</acronym> sollte um alle Programmcode-Abschnitte vorhanden sein.
            </para>

            <para>
                <emphasis>&lt;programlisting&gt;</emphasis> Abschnitte dürfen keine Zeilenumbrüche
                oder Leerzeichen am Anfang oder Ende des Abschnitts besitzen, da diese auch in der
                endgültigen Ausgabe dargestellt werden.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[

$render = "xxx";

]]]]>&gt;<![CDATA[</programlisting>

<!-- OK -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                Endende <acronym>CDATA</acronym> und <emphasis>&lt;programlisting&gt;</emphasis>
                Tags sollten in der gleichen Zeile, aber ohne Einrückung stehen.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[
    </programlisting>

<!-- NICHT ERLAUBT -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
    ]]]]>&gt;<![CDATA[</programlisting>

<!-- OK -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                Das <emphasis>&lt;programlisting&gt;</emphasis> Tag sollte das "language" Attribut
                mit einem Wert enthalten, der dem Inhalt des Programmcode-Abschnitts entspricht.
                Typischerweise enthält es die Werte "css", "html", "ini", "javascript", "php",
                "text", und "xml".
            </para>

            <programlisting language="xml"><![CDATA[
<!-- PHP -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[

<!-- Javascript -->
<programlisting language="javascript">]]>&lt;<![CDATA[![CDATA[

<!-- XML -->
<programlisting language="xml">]]>&lt;<![CDATA[![CDATA[
]]></programlisting>

            <para>
                Für Programmcode-Abschnitte, die nur <acronym>PHP</acronym> Code enthalten, werden
                keine <acronym>PHP</acronym>-Tags (wie z.B. "&lt;?php", "?&gt;") benötigt, und
                sollten auch nicht verwendet werden. Sie zeigen nur das Naheliegendste und werden
                durch die Verwendung des <emphasis>&lt;programlisting&gt;</emphasis> Tags
                impliziert.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<programlisting language="php"]]>&lt;<![CDATA[![CDATA[<?php
    // ...
?>]]]]>&gt;<![CDATA[</programlisting>

<programlisting language="php"]]>&lt;<![CDATA[![CDATA[
<?php
    // ...
?>
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                Die Zeilenlängen in Programmcode-Abschnitten sollten den <link
                    linkend="coding-standard.php-file-formatting.max-line-length">Coding Standard
                    Empfehlungen</link> folgen.
            </para>

            <para>
                <methodname>require_once()</methodname>, <methodname>require()</methodname>,
                <methodname>include_once()</methodname> und <methodname>include()</methodname>
                sollten innerhalb von <acronym>PHP</acronym>-Listings nicht verwendet werden.
                Sie zeigen nur das Naheliegendste, und sind meistens nicht notwendig, wenn ein
                Autoloader verwendet wird. Sie sollten nur verwendet werden, wenn sie essentiell
                für das Beispiel sind.
            </para>

            <note>
                <title>Niemals Short Tags verwenden</title>

                <para>
                    Short Tags (z.B., "&lt;?", "&lt;?=") sollten niemals innerhalb von
                    <emphasis>programlisting</emphasis> oder eines Dokuments verwendet werden.
                </para>
            </note>
        </sect2>

        <sect2 id="doc-standard.file-formatting.inline-tags">
            <title>Notizen zu speziellen Inline Tags</title>

            <sect3 id="doc-standard.file-formatting.inline-tags.classname">
                <title>classname</title>

                <para>
                    Das Tag <emphasis>&lt;classname&gt;</emphasis> muß jedesmal verwendet werden,
                    wenn ein Klassenname durch sich selbst repräsentiert wird; er sollte nicht
                    in Kombination mit einem Methodennamen, Variablennamen, oder einer Konstante
                    verwendet werden, und auch anderer Inhalt ist nicht innerhalb des Tags erlaubt.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Die Klasse <classname>Zend_Class</classname>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.varname">
                <title>varname</title>

                <para>
                    Variablen müssen im <emphasis>&lt;varname&gt;</emphasis> Tag eingeschlossen sein.
                    Variablen müssen mit Verwendung des "$" Siegels geschrieben werden. Kein
                    anderer Inhalt ist innerhalb des Tags erlaubt, ausser es wird ein Klassenname
                    verwendet, der eine Klassenvariable anzeigt.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Die Variable <varname>$var</varname> und die Klassenvariable
    <varname>Zend_Class::$var</varname>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.methodname">
                <title>methodname</title>

                <para>
                    Methoden müssen innerhalb des <emphasis>&lt;methodname&gt;</emphasis> Tags
                    stehen. Methoden müssen entweder die komplette Methoden Signatur enthalten,
                    oder zumindest ein Paar schließender Klammern (z.B., "()"). Kein anderer
                    Inhalt ist innerhalb dieses Tags erlaubt, ausser es wird ein Klassenname
                    verwendet, der eine Klassenmethode anzeigt.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Die Methode <methodname>foo()</methodname> und die Klassenmethode
    <methodname>Zend_Class::foo()</methodname>. Eine Methode mit der kompletten
    Signatur <methodname>foo($bar, $baz)</methodname>
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.constant">
                <title>constant</title>

                <para>
                    Das <emphasis>&lt;constant&gt;</emphasis> Tag ist zu verwenden wenn Konstanten
                    angezeigt werden sollen. Konstanten müssen <acronym>GROßGESCHRIEBEN</acronym>
                    werden. Kein anderer Inhalt ist innerhalb dieses Tags erlaubt, ausser es wird
                    ein Klassenname verwendet, der eine Klassenkonstante anzeigt.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Die Konstante <constant>FOO</constant> und die Klassenkonstante
    <constant>Zend_Class::FOO</constant>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.filename">
                <title>filename</title>

                <para>
                    Dateinamen und Pfade müssen im <emphasis>&lt;filename&gt;</emphasis> Tag
                    enthalten sein. Kein anderer Inhalt ist innerhalb dieses Tags erlaubt.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Die Datei <filename>application/Bootstrap.php</filename>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.command">
                <title>command</title>

                <para>
                    Commands, Shell Skripte, und Programmaufrufe müssen im
                    <emphasis>&lt;command&gt;</emphasis> Tag enthalten sein. Wenn das Kommando
                    Argumente enthält sollten diese auch im Tag enthalten sein.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Ausführen von <command>zf.sh create project</command>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.code">
                <title>code</title>

                <para>
                    Die Verwendung des <emphasis>&lt;code&gt;</emphasis> Tags ist nicht erlaubt.
                    Stattdessen sollten die anderen vorher besprochenen Inline Tags verwendet
                    werden.
                </para>
            </sect3>
        </sect2>

        <sect2 id="doc-standard.file-formatting.block-tags">
            <title>Notizen zu speziellen Block Tags</title>

            <sect3 id="doc-standard.file-formatting.block-tags.title">
                <title>title</title>

                <para>
                    Das <emphasis>&lt;title&gt;</emphasis> Tag darf keine anderen Tags enthalten.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NICHT ERLAUBT -->
<title>Verwendung von <classname>Zend_Class</classname></title>

<!-- OK -->
<title>Verwendung von Zend_Class</title>
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>

    <sect1 id="doc-standard.recommendations">
        <title>Empfehlungen</title>

        <sect2 id="doc-standard.recommendations.editors">
            <title>Editoren ohne Autoformatierung verwenden</title>

            <para>
                Für die Bearbeitung der Dokumentation sollten typischerweise keine formalen
                <acronym>XML</acronym>-Editoren verwendet werden. Solche Editoren formatieren
                bestehende Dokumente normalerweise so, dass diese ihren eigenen Standards folgen
                und folgen dem Docbook Standard nicht strikt. Als Beispiel haben wir gesehen
                das sie die <acronym>CDATA</acronym> Tags entfernen, die Trennung von 4 Leerzeichen
                zu Tabs oder 2 Leerzeichen  ändern, usw.
            </para>

            <para>
                Die Styling Richtlinien wurde großteils geschrieben, um Übersetzern zu helfen, damit
                diese durch Verwendung von normalen <command>diff</command>-Tools erkennen, welche
                Zeilen sich geändert haben. Die automatische Formatierung macht diesen Prozess
                viel schwieriger.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.images">
            <title>Verwendung von Bildern</title>

            <para>
                Gute Bilder und Diagramme können die Lesbarkeit und das Verständnis erhöhen. Sie
                sollten immer dann verwendet werden, wenn sie diesen Zielen helfen. Bilder sollten
                im Verzeichnis <filename>documentation/manual/en/figures/</filename> platziert,
                und nach dem Kapitel benannt werden, in dem sie vorkommen.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.examples">
            <title>Gute Fallbeispiele</title>

            <para>
                Man sollte nach guten Fallbeispielen suchen, die von der Community verbreitet werden.
                Speziell jene, die in den Kommentaren der Proposals oder einer der Mailing Listen
                gesendet werden. Beispiel zeigen oft viel besser die Verwendung, als es
                Beschreibungen tun.
            </para>

            <para>
                Wenn man Beispiele für die Aufnahme in das Handbuch schreibt, sollte man
                allen Coding Standards und Dokumentations Standards folgen.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.phpdoc">
            <title>Vermeide die Wiederholung von phpdoc Inhalten</title>

            <para>
                Das Handbuch ist dazu gedacht, ein Referenzhandbuch für die Verwendung durch
                Endbenutzer zu sein. Die Wiederholung von phpdoc Dokumentation für intern
                verwendete Komponenten und Klassen ist nicht erwünscht, und die Beschreibungen
                sollten auf die Verwendung fokussiert sein, und nicht der internen Arbeitsweise.
                In jedem Fall und zu jeder Zeit wollen wir, dass sich die Dokumentations-Teams auf
                die Übersetzung des englischen Handbuchs und nicht auf ide phpdoc Kommentare
                fokussiert.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.links">
            <title>Verwendung von Links</title>

            <para>
                Links sollten zu anderen Abschnitten des Handbuchs oder externen Quellen verweisen,
                statt Dokumentation zu wiederholen.
            </para>

            <para>
                Die Verlinkung zu anderen Abschnitten des Handbuchs kann durchgeführt werden, indem
                das <emphasis>&lt;link&gt;</emphasis> Tag verwendet wird (für welches man den Link
                Text selbst angeben muß).
            </para>

            <programlisting language="xml"><![CDATA[
<para>
    "Link" verweist zu einer Sektion, und verwendet beschreibenden Text: <link
        linkend="doc-standard.recommendations.links">Dokumentation zum
        Link</link>.
</para>
]]></programlisting>

            <para>
                Um auf eine externe Ressource zu verweisen, muss <emphasis>&lt;ulink&gt;</emphasis>
                verwendet werden:
            </para>

            <programlisting language="xml"><![CDATA[
<para>
    Die <ulink url="http://framework.zend.com/">Zend Framework Seite</ulink>.
</para>
]]></programlisting>
        </sect2>
    </sect1>
</appendix>