# Zend Framework Dokumentations Standard

## Übersicht

### Ziele

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 `diff` Tools.

Man kann diese Standards zusammen mit den Regeln unserer Lizenz adoptieren und oder modifizieren.

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

## Formatierung von Dokumentationsdateien

### XML Tags

Jede Datei des Manuals muss die folgenden XML Deklarationen am Beginn der Datei enthalten:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Reviewed: no -->

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

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 14978 -->
    <!-- Reviewed: no -->

### Maximale Zeilenlänge

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.

### Einrückung

Eine Einrückung sollte aus 4 Leerzeichen bestehen. Tabulatoren sind nicht erlaubt.

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

    <sect1>
    </sect1>

    <sect1>
    </sect1>

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

    <sect1>
        <sect2>
        </sect2>
    </sect1>

Mehrere Block Tags in der gleichen Zeile sind nicht erlaubt; mehrere Inline Tags sind trotzdem erlaubt.

    <!-- NICHT ERLAUBT -->
    <sect1><sect2>
    </sect2></sect1>

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

### Zeilenendekennzeichen

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.

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

### Leere Tags

Leere Tags sind nicht erlaubt; alle Tags müssen Text oder Untertags enthalten.

    <!-- NICHT ERLAUBT -->
    <para>
        Irgendein Text. <link></link>
    </para>

    <para>
    </para>

### Verwendung von Leerzeichen in Dokumenten

#### Leerzeichen in Tags

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

    <!-- NICHT ERLAUBT -->
    <sect1>LEERZEICHEN
    </sect1>

Öffnende Inline Tags sollten keine Leerzeichen haben, die direkt folgen.

    <!-- NICHT ERLAUBT -->
    Das ist die Klasse <classname> Zend_Class</classname>.

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

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

    <!-- NICHT ERLAUBT -->
        <sect1>
         </sect1>

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

Schließenden Inline Tags dürfen keine Leerzeichen vorangestellt sein.

    <!-- NICHT ERLAUBT -->
    Das ist die Klasse <classname>Zend_Class </classname>

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

#### Mehrere Zeilenumbrüche

Mehrere Zeilenumbrüche innerhalb oder auch zwischen Tags sind nicht erlaubt.

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

#### Trennung zwischen Tags

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

    <!-- NICHT ERLAUBT -->
    <para>
        Etwas Text...
    </para>
    <para>
        Mehr Text...
    </para>

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

    <para>
        Mehr Text...
    </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.

    <!-- NICHT ERLAUBT -->
    <sect1>

        <sect2>
        </sect2>

        <sect2>
        </sect2>

        <sect2>
        </sect2>

    </sect1>

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

        <sect2>
        </sect2>

        <sect2>
        </sect2>
    </sect1>

### Programmcode-Abschnitte

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

    <para>Vorhergehender Paragraph.</para>

    <programlisting language="php"><![CDATA[

CDATA sollte um alle Programmcode-Abschnitte vorhanden sein.

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

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

    $render = "xxx";

    ]]></programlisting>

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

Endende CDATA und <programlisting> Tags sollten in der gleichen Zeile, aber ohne Einrückung stehen.

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

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

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

Das <programlisting> 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".

    <!-- PHP -->
    <programlisting language="php"><![CDATA[

    <!-- Javascript -->
    <programlisting language="javascript"><![CDATA[

    <!-- XML -->
    <programlisting language="xml"><![CDATA[

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

    <!-- NICHT ERLAUBT -->
    <programlisting language="php"<![CDATA[<?php
        // ...
    ?>]]></programlisting>

    <programlisting language="php"<![CDATA[
    <?php
        // ...
    ?>
    ]]></programlisting>

Die Zeilenlängen in Programmcode-Abschnitten sollten den Coding Standard Empfehlungen folgen.

require_once(), require(), include_once() und include() sollten innerhalb von PHP-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.

Niemals Short Tags verwenden

Short Tags (z.B., "<?", "<?=") sollten niemals innerhalb von programlisting oder eines Dokuments verwendet werden.

### Notizen zu speziellen Inline Tags

#### classname

Das Tag <classname> 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>
        Die Klasse <classname>Zend_Class</classname>.
    </para>

#### varname

Variablen müssen im <varname> 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>
        Die Variable <varname>$var</varname> und die Klassenvariable
        <varname>Zend_Class::$var</varname>.
    </para>

#### methodname

Methoden müssen innerhalb des <methodname> 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>
        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>

#### constant

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

    <para>
        Die Konstante <constant>FOO</constant> und die Klassenkonstante
        <constant>Zend_Class::FOO</constant>.
    </para>

#### filename

Dateinamen und Pfade müssen im <filename> Tag enthalten sein. Kein anderer Inhalt ist innerhalb dieses Tags erlaubt.

    <para>
        Die Datei <filename>application/Bootstrap.php</filename>.
    </para>

#### command

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

    <para>
        Ausführen von <command>zf.sh create project</command>.
    </para>

#### code

Die Verwendung des <code> Tags ist nicht erlaubt. Stattdessen sollten die anderen vorher besprochenen Inline Tags verwendet werden.

### Notizen zu speziellen Block Tags

#### title

Das <title> Tag darf keine anderen Tags enthalten.

    <!-- NICHT ERLAUBT -->
    <title>Verwendung von <classname>Zend_Class</classname></title>

    <!-- OK -->
    <title>Verwendung von Zend_Class</title>

## Empfehlungen

### Editoren ohne Autoformatierung verwenden

Für die Bearbeitung der Dokumentation sollten typischerweise keine formalen XML-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 CDATA Tags entfernen, die Trennung von 4 Leerzeichen zu Tabs oder 2 Leerzeichen ändern, usw.

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

### Verwendung von Bildern

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 `documentation/manual/en/figures/` platziert, und nach dem Kapitel benannt werden, in dem sie vorkommen.

### Gute Fallbeispiele

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.

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

### Vermeide die Wiederholung von phpdoc Inhalten

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.

### Verwendung von Links

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

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

    <para>
        "Link" verweist zu einer Sektion, und verwendet beschreibenden Text: <link
            linkend="doc-standard.recommendations.links">Dokumentation zum
            Link</link>.
    </para>

Um auf eine externe Ressource zu verweisen, muss <ulink> verwendet werden:

    <para>
        Die <ulink url="http://framework.zend.com/">Zend Framework Seite</ulink>.
    </para>