Format des fichiers de documentation

Balises XML

Chaque fichier du manuel doit inclure la déclaration XML suivante à la première ligne du fichier :

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

Les fichiers XML provenant des traductions doivent également inclure le tag de révision correspondant au fichier original en anglais duquel la traduction est tirée.

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

Longueur maximum d'une ligne

La longueur maximum d'une ligne, incluant les balises, les attributs, l'indentation ne doit pas excéder 100 caractères. Il existe une seule exception à cette règle, un couple attribut / valeur peut excéder 100 caractères puisqu'il n'est pas autorisé de les séparer.

Indentation

L'indentation est faite de 4 espaces. Les tabulations ne sont pas autorisées.

Les éléments qui sont aux même niveaux doivent avoir la même indentation.

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

Les éléments qui sont un niveau en-dessous de l'élément précédent doivent être indentés de 4 espaces supplémentaires.

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

Plusieurs éléments bloc sur une même ligne ne sont pas autorisés ; plusieurs éléments en-ligne le sont en revanche.

<!-- NON AUTORISÉ : -->
<sect1><sect2>
</sect2></sect1>
<!-- AUTORISÉ -->
<para>
    <classname>Zend_Magic</classname> n'existe pas. <classname>Zend_Acl</classname> existe.
</para>

Fin de ligne

Les fins de ligne suivent les conventions de fichier Unix. Les lignes doivent être terminées par un seul saut de ligne (LF), le caractère de saut de ligne s'écrit 10 en notation ordinal 10, et 0x0A en hexadécimal.

Note : N'utilisez pas les retours chariot (CR) comme c'est le cas sur les systèmes Apple, ni l'association d'un retour chariot avec un saut de ligne (CRLF) qui est le standard sur les systèmes Windows (0X0D, 0x0A).

Éléments vides

Les éléments vides ne sont pas autorisés, tous les éléments doivent contenir du texte ou des éléments enfants.

<!-- NON AUTORISÉ : -->
<para>
    Lorem ipsum. <link></link>
</para>
<para>
</para>

Utilisation des espaces dans les documents

Espace entre les balises

Les balises ouvrantes des éléments bloc ne devrait pas être suivi par autre chose qu'un saut de ligne (et l'indentation de la ligne suivante).

<!-- NON AUTORISÉ : -->
<sect1>ESPACE
</sect1>

Les balises ouvrantes des éléments en-ligne ne devrait pas être suivi d'espace.

<!-- NON AUTORISÉ : -->
C'est la classe <classname> Zend_Class</classname>.
<!-- AUTORISÉ : -->
C'est la classe <classname>Zend_Class</classname>.

Les balises des éléments bloc peuvent être précédés par des espaces, si ceux-ci sont équivalents aux nombres d'espaces nécessaires pour l'indentation, mais pas plus.

<!-- NON AUTORISÉ : -->
    <sect1>
     </sect1>
<!-- AUTORISÉ : -->
    <sect1>
    </sect1>

Les balises des éléments en-ligne ne doivent pas être précédés d'espaces.

<!-- NON AUTORISÉ -->
C'est la classe <classname>Zend_Class </classname>
<!-- AUTORISÉ -->
C'est la classe  <classname>Zend_Class</classname>

Sauts de ligne multiples

Les sauts de ligne multiples ne sont pas autorisés ni dans les balises, ni entre elles.

<!-- NON AUTORISÉ -->
<para>
    Lorem ipsum...
    ... dolor sid amet
</para>


<para>
    Un autre paragraphe.
</para>
<!-- AUTORISÉ -->
<para>
    Lorem ipsum...
    ... dolor sid amet
</para>

<para>
    Un autre paragraphe.
</para>

Séparation entre les balises

Les éléments qui sont au même niveau doivent être séparés par une ligne vide pour améliorer la lisibilité.

<!-- NON AUTORISÉ -->
<para>
    Lorem ipsum...
</para>
<para>
    Dolor sid amet...
</para>
<!-- AUTORISÉ -->
<para>
    Lorem ipsum...
</para>

<para>
    Dolor sid amet...
</para>

Le premier élément enfant devrait être ouvert directement après son parent, sans ligne vide entre eux ; le dernier élément enfant quant à lui, devrait être fermé juste avant la balise fermante de son parent.

<!-- NON AUTORISÉ -->
<sect1>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

</sect1>
<!-- AUTORISÉ -->
<sect1>
    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>
</sect1>

Exemple de code

La balise ouvrante de l'élement <programlisting> doit indiquer l'attribut de langage (language) approprié et doit être indenté au même niveau que ces blocs frères.

<para>Paragraphe frère.</para>
<programlisting language="php"><![CDATA[

CDATA devrait être utilisé autour de tous les exemples de code.

Les sections <programlisting> ne doivent pas contenir de saut de ligne ou d'espace ni au début ni à la fin, étant donné qu'ils sont représentés tels quels.

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

La fermeture des éléments CDATA et <programlisting> devrait être sur la même ligne, sans aucune indentation.

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

L'élément <programlisting> devrait contenir l'attribut de langage avec la valeur appropriée au contenu. Les valeurs les plus courantes sont "css", "html", "ini", "javascript", "text", et "xml".

<!-- PHP -->
<programlisting language="php"><![CDATA[
<!-- Javascript -->
<programlisting language="javascript"><![CDATA[
<!-- XML -->
<programlisting language="xml"><![CDATA[

Pour les exemples contenant uniquement du code PHP, Les balises PHP ("<?php" et "?>") ne sont pas requises, et ne devrait pas être utilisées. Elles compliquent la lisibilité du code, et sont implicites lors de l'utilisation de l'élément <programlisting>.

<!-- NON AUTORISÉ -->
<programlisting language="php"<![CDATA[<?php
    // ...
?>]]></programlisting>
<programlisting language="php"<![CDATA[
<?php
    // ...
?>
]]></programlisting>

La longueur maximum des lignes pour les exemples de code devrait suivre les recommandations de la convention de codage.

Évitez d'utiliser require_once(), require(), include_once(), et include() dans les exemples PHP. Ils emcombrent la documentation, et sont la plupart du temps inutile si vous utilisez un autoloader. Utilisez-les uniquement lorsqu'ils sont essentiels à la compréhension d'un exemple.

N'utilisez jamais les short tags

Les short tags (e.g., "<?", "<?=") ne devrait jamais être utilisés dans l'élément programlisting ni dans le reste de la documentation.

Notes spécifiques sur les éléments en-ligne

classname

L'élément <classname> doit être utilisé chaque fois que le nom d'une classe est mentionné ; il ne doivent cependant pas être utilisé lorsque celle-ci est associé au nom d'une méthode, d'un membre, ou d'une constante, rien d'autre n'est autorisé dans cet élément.

<para>
    La classe <classname>Zend_Class</classname>.
</para>

varname

Les variables doivent être entourées par les balises <varname> . Les variables doivent être écrites en utilisant le symbole "$". Rien d'autre n'est autorisé dans cet élément, excepté le nom d'une classe, s'il s'agit d'un membre de celle-ci.

<para>
    La variable <varname>$var</varname> et le membre de classe
    <varname>Zend_Class::$var</varname>.
</para>

methodname

Les méthodes doivent être entourées par les balises <methodname>. Les méthodes doivent soit contenir la signature complète, soit au moins une paire de parenthèses (ex : "()"). Aucun autre contenu n'est autorisé dans cet élément, excepté le nom d'une classe, pour indiquer qu'il s'agit d'une méthode de celle-ci.

<para>
    La fonction <methodname>foo()</methodname> et la méthode
    <methodname>Zend_Class::foo()</methodname>. Une fonction avec une signature :
    <methodname>foo($bar, $baz)</methodname>
</para>

constant

Utilisez l'élément <constant> pour indiquer qu'il s'agit d'une constante. Les constantes doivent être écrites en majuscules. Aucun autre contenu n'est autorisé, excepté le nom d'une classe, pour indiquer qu'il s'agit d'une constante de classe.

<para>
    La constante <constant>FOO</constant> et la constante de classe
    <constant>Zend_Class::FOO</constant>.
</para>

filename

Les noms de fichier et chemins doivent être entourés par les balises <filename>. Aucun autre contenu n'est autorisé dans cet élément.

<para>
    Le nom de fichier <filename>application/Bootstrap.php</filename>.
</para>

command

Les commandes, les scripts shell, ainsi que l'appel de programme doivent être entourés par les balises <command>. Si la commande nécessite des arguments, ceux-ci doivent également être présent.

<para>
    Executez <command>zf.sh create project</command> pour créer un projet.
</para>

code

L'utilisation de l'élément <code> est déconseillée, en faveur des autres éléments discutés précédement.

Notes spécifiques sur les éléments bloc

title

L'élément <title> ne peut pas contenir d'éléments enfants.

<!-- NON AUTORISÉ -->
<title>Utilisation de <classname>Zend_Class</classname></title>
<!-- AUTORISÉ -->
<title>Utilisation de Zend_Class</title>