|
|
@@ -0,0 +1,657 @@
|
|
|
+<?xml version="1.0" encoding="utf-8"?>
|
|
|
+<!-- EN-Revision: 20876 -->
|
|
|
+<!-- Reviewed: no -->
|
|
|
+<appendix id="doc-standard">
|
|
|
+ <title>Recommandation sur la documentation de Zend Framework</title>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.overview">
|
|
|
+ <title>Présentation</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.overview.scope">
|
|
|
+ <title>Cadre</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ce document fournit les lignes directrices pour la création de documentation pour
|
|
|
+ Zend Framework. Il s'agit d'un guide pour les contributeurs, qui doivent écrire la
|
|
|
+ documentation nécessaire lors de la contribution d'un composant, mais aussi pour
|
|
|
+ les traducteurs. Les recommandations contenues dans le présent document ont pour
|
|
|
+ objectif de faciliter la traduction de la documentation, de minimiser les
|
|
|
+ différences visuelles et stylistiques entre les différents fichiers, et de
|
|
|
+ faciliter la recherche de différences avec la commande <command>diff</command>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Vous pouvez adopter et/ou modifier ces recommandations tant que vous respectez
|
|
|
+ les termes de notre <ulink url="http://framework.zend.com/license">license</ulink>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les sujets couverts dans ce document incluent le format des fichiers ainsi que des
|
|
|
+ recommandations sur le maintien de la qualité de la documentation.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.file-formatting">
|
|
|
+ <title>Format des fichiers de documentation</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.xml-tags">
|
|
|
+ <title>Balises XML</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Chaque fichier du manuel doit inclure la déclaration <acronym>XML</acronym>
|
|
|
+ suivante à la première ligne du fichier :
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- Reviewed: no -->
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les fichiers <acronym>XML</acronym> provenant des traductions doivent également
|
|
|
+ inclure le tag de révision correspondant au fichier original en anglais duquel la
|
|
|
+ traduction est tirée.
|
|
|
+ </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>Longueur maximum d'une ligne</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.indentation">
|
|
|
+ <title>Indentation</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ L'indentation est faite de 4 espaces. Les tabulations ne sont pas autorisées.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>Les éléments qui sont aux même niveaux doivent avoir la même indentation.</para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<sect1>
|
|
|
+</sect1>
|
|
|
+<sect1>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<sect1>
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Plusieurs éléments bloc sur une même ligne ne sont pas autorisés ; plusieurs
|
|
|
+ éléments en-ligne le sont en revanche.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ : -->
|
|
|
+<sect1><sect2>
|
|
|
+</sect2></sect1>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+<para>
|
|
|
+ <classname>Zend_Magic</classname> n'existe pas. <classname>Zend_Acl</classname> existe.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.line-termination">
|
|
|
+ <title>Fin de ligne</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Note : N'utilisez pas les retours chariot (<acronym>CR</acronym>) comme c'est le
|
|
|
+ cas sur les systèmes Apple, ni l'association d'un retour chariot avec un saut de
|
|
|
+ ligne (<acronym>CRLF</acronym>) qui est le standard sur les systèmes Windows
|
|
|
+ (0X0D, 0x0A).
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.empty-tags">
|
|
|
+ <title>Éléments vides</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les éléments vides ne sont pas autorisés, tous les éléments doivent
|
|
|
+ contenir du texte ou des éléments enfants.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ : -->
|
|
|
+<para>
|
|
|
+ Lorem ipsum. <link></link>
|
|
|
+</para>
|
|
|
+<para>
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.whitespace">
|
|
|
+ <title>Utilisation des espaces dans les documents</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.trailing">
|
|
|
+ <title>Espace entre les balises</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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).
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ : -->
|
|
|
+<sect1>ESPACE
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les balises ouvrantes des éléments en-ligne ne devrait pas être suivi
|
|
|
+ d'espace.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ : -->
|
|
|
+C'est la classe <classname> Zend_Class</classname>.
|
|
|
+<!-- AUTORISÉ : -->
|
|
|
+C'est la classe <classname>Zend_Class</classname>.
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ : -->
|
|
|
+ <sect1>
|
|
|
+ </sect1>
|
|
|
+<!-- AUTORISÉ : -->
|
|
|
+ <sect1>
|
|
|
+ </sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les balises des éléments en-ligne ne doivent pas être précédés d'espaces.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+C'est la classe <classname>Zend_Class </classname>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+C'est la classe <classname>Zend_Class</classname>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.multiple-line-breaks">
|
|
|
+ <title>Sauts de ligne multiples</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les sauts de ligne multiples ne sont pas autorisés ni dans les balises,
|
|
|
+ ni entre elles.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- 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>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.tag-separation">
|
|
|
+ <title>Séparation entre les balises</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les éléments qui sont au même niveau doivent être séparés par une ligne vide
|
|
|
+ pour améliorer la lisibilité.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+<para>
|
|
|
+ Lorem ipsum...
|
|
|
+</para>
|
|
|
+<para>
|
|
|
+ Dolor sid amet...
|
|
|
+</para>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+<para>
|
|
|
+ Lorem ipsum...
|
|
|
+</para>
|
|
|
+
|
|
|
+<para>
|
|
|
+ Dolor sid amet...
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+<sect1>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+</sect1>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+<sect1>
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.program-listing">
|
|
|
+ <title>Exemple de code</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ La balise ouvrante de l'élement <emphasis><programlisting></emphasis> doit
|
|
|
+ indiquer l'attribut de langage (language) approprié et doit être indenté au même
|
|
|
+ niveau que ces blocs frères.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>Paragraphe frère.</para>
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <acronym>CDATA</acronym> devrait être utilisé autour de tous les exemples de code.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les sections <emphasis><programlisting></emphasis> 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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ La fermeture des éléments <acronym>CDATA</acronym> et <emphasis><programlisting></emphasis>
|
|
|
+ devrait être sur la même ligne, sans aucune indentation.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[
|
|
|
+ </programlisting>
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+ ]]]]>><![CDATA[</programlisting>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ L'élément <emphasis><programlisting></emphasis> 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".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- PHP -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+<!-- Javascript -->
|
|
|
+<programlisting language="javascript">]]><<![CDATA[![CDATA[
|
|
|
+<!-- XML -->
|
|
|
+<programlisting language="xml">]]><<![CDATA[![CDATA[
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Pour les exemples contenant uniquement du code <acronym>PHP</acronym>,
|
|
|
+ Les balises <acronym>PHP</acronym> ("<?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
|
|
|
+ <emphasis><programlisting></emphasis>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+<programlisting language="php"]]><<![CDATA[![CDATA[<?php
|
|
|
+ // ...
|
|
|
+?>]]]]>><![CDATA[</programlisting>
|
|
|
+<programlisting language="php"]]><<![CDATA[![CDATA[
|
|
|
+<?php
|
|
|
+ // ...
|
|
|
+?>
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ La longueur maximum des lignes pour les exemples de code devrait suivre les
|
|
|
+ recommandations de la <link linkend="coding-standard.php-file-formatting.max-line-length">
|
|
|
+ convention de codage</link>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Évitez d'utiliser <methodname>require_once()</methodname>,
|
|
|
+ <methodname>require()</methodname>, <methodname>include_once()</methodname>, et
|
|
|
+ <methodname>include()</methodname> dans les exemples <acronym>PHP</acronym>.
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <title>N'utilisez jamais les short tags</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les short tags (e.g., "<?", "<?=") ne devrait jamais être utilisés dans
|
|
|
+ l'élément <emphasis>programlisting</emphasis> ni dans le reste de la
|
|
|
+ documentation.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.inline-tags">
|
|
|
+ <title>Notes spécifiques sur les éléments en-ligne</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.classname">
|
|
|
+ <title>classname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ L'élément <emphasis><classname></emphasis> 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>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ La classe <classname>Zend_Class</classname>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.varname">
|
|
|
+ <title>varname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les variables doivent être entourées par les balises <emphasis><varname>
|
|
|
+ </emphasis>.
|
|
|
+ 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>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ La variable <varname>$var</varname> et le membre de classe
|
|
|
+ <varname>Zend_Class::$var</varname>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.methodname">
|
|
|
+ <title>methodname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les méthodes doivent être entourées par les balises
|
|
|
+ <emphasis><methodname></emphasis>. 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>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<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>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.constant">
|
|
|
+ <title>constant</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Utilisez l'élément <emphasis><constant></emphasis> 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>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ La constante <constant>FOO</constant> et la constante de classe
|
|
|
+ <constant>Zend_Class::FOO</constant>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.filename">
|
|
|
+ <title>filename</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les noms de fichier et chemins doivent être entourés par les balises
|
|
|
+ <emphasis><filename></emphasis>. Aucun autre contenu n'est autorisé
|
|
|
+ dans cet élément.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ Le nom de fichier <filename>application/Bootstrap.php</filename>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.command">
|
|
|
+ <title>command</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les commandes, les scripts shell, ainsi que l'appel de programme doivent être
|
|
|
+ entourés par les balises <emphasis><command></emphasis>. Si la commande
|
|
|
+ nécessite des arguments, ceux-ci doivent également être présent.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ Executez <command>zf.sh create project</command> pour créer un projet.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.code">
|
|
|
+ <title>code</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ L'utilisation de l'élément <emphasis><code></emphasis> est déconseillée,
|
|
|
+ en faveur des autres éléments discutés précédement.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.block-tags">
|
|
|
+ <title>Notes spécifiques sur les éléments bloc</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.block-tags.title">
|
|
|
+ <title>title</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ L'élément <emphasis><title></emphasis> ne peut pas contenir d'éléments enfants.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NON AUTORISÉ -->
|
|
|
+<title>Utilisation de <classname>Zend_Class</classname></title>
|
|
|
+<!-- AUTORISÉ -->
|
|
|
+<title>Utilisation de Zend_Class</title>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.recommendations">
|
|
|
+ <title>Recommendations</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.editors">
|
|
|
+ <title>Utilisez un éditeur sans formatage automatique</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Pour éditer la documentation, vous ne devriez pas utiliser un éditeur
|
|
|
+ <acronym>XML</acronym> classique. Ces éditeurs formattent pour la plupart
|
|
|
+ automatiquement les documents pour s'adapter à leurs propres standards et/ou ne
|
|
|
+ suivent pas strictement les recommandations du docbook. Par exemple, nous en
|
|
|
+ avons vu certains d'entre eux supprimer l'élément <acronym>CDATA</acronym>,
|
|
|
+ remplacer 4 espaces par des tabulations, ou 2 espaces, etc.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ces recommandations ont été écrites en grande partie afin d'aider les traducteurs
|
|
|
+ à déterminer les changements en utilisant la commande <command>diff</command>.
|
|
|
+ Le formatage automatique rend cette opération plus difficile.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.images">
|
|
|
+ <title>Utilisez des images</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les images et les diagrammes peuvent améliorer la lisibilité et la compréhension.
|
|
|
+ Utilisez les chaque fois qu'ils le permettent. Les images devrait être placées
|
|
|
+ dans le répertoire <filename>documentation/manual/en/figures/</filename>, et
|
|
|
+ nommées juste après l'identifiant de la section qui les concerne.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.examples">
|
|
|
+ <title>Utilisez des cas d'utilisations</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Cherchez de bons cas d'utilisation soumis par la communauté, particulièrement
|
|
|
+ ceux des commentaires dans les propositions ou encore sur l'une des liste de
|
|
|
+ discussion. Un exemple vaut mieux qu'un long discours.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Lorsque vous écrivez des exemples à inclure dans le manuel, suivez les conventions
|
|
|
+ de codages ainsi que les recommandations pour la documentation.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.phpdoc">
|
|
|
+ <title>Évitez de répéter le contenu des phpdoc</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ce manuel a pour objectif d'être une référence pour l'utilisateur final.
|
|
|
+ Recopier la documentation phpdoc pour expliquer le fonctionnenement interne des
|
|
|
+ composants et des classes n'est pas souhaité, l'accent devrait être mis sur
|
|
|
+ l'utilisation. Dans tous les cas, nous souhaiterions que l'équide de documentation
|
|
|
+ se concentre sur la traduction du manuel anglais, et non pas les commentaires
|
|
|
+ phpdoc.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.links">
|
|
|
+ <title>Utilisez des liens</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Créez des liens vers les autres sections ou des ressources externes plutôt que
|
|
|
+ de tout réécrire.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Les liens vers d'autres sections du manuel peuvent aussi bien utiliser l'élement
|
|
|
+ <emphasis><xref></emphasis> (qui substitura le titre de la section pour
|
|
|
+ créer le nom du lien) ou l'élément <emphasis><link></emphasis> (pour lequel
|
|
|
+ vous devez fournir le nom du lien).
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ "Xref" crée un lien vers la section : <xref
|
|
|
+ linkend="doc-standard.recommendations.links" />.
|
|
|
+</para>
|
|
|
+<para>
|
|
|
+ "Link" crée un lien vers une section, et utilise un titre explicite : <link
|
|
|
+ linkend="doc-standard.recommendations.links">documentation sur la créer de liens</link>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Pour créer un lien vers une ressource externe utilisez l'élément
|
|
|
+ <emphasis><ulink></emphasis> :
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ Le site du <ulink url="http://framework.zend.com/">Zend Framework</ulink>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+</appendix>
|
mikaelkael