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 diff. Vous pouvez adopter et/ou modifier ces recommandations tant que vous respectez les termes de notre license. Les sujets couverts dans ce document incluent le format des fichiers ainsi que des recommandations sur le maintien de la qualité de la documentation. Chaque fichier du manuel doit inclure la déclaration XML suivante à la première ligne du fichier : ]]> 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. ]]> 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. 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. ]]> 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. ]]> Plusieurs éléments bloc sur une même ligne ne sont pas autorisés ; plusieurs éléments en-ligne le sont en revanche. Zend_Magic n'existe pas. Zend_Acl existe. ]]> 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). Les éléments vides ne sont pas autorisés, tous les éléments doivent contenir du texte ou des éléments enfants. Lorem ipsum. ]]> 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). ESPACE ]]> Les balises ouvrantes des éléments en-ligne ne devrait pas être suivi d'espace. C'est la classe Zend_Class. C'est la classe Zend_Class. ]]> 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. ]]> Les balises des éléments en-ligne ne doivent pas être précédés d'espaces. C'est la classe Zend_Class C'est la classe Zend_Class ]]> Les sauts de ligne multiples ne sont pas autorisés ni dans les balises, ni entre elles. Lorem ipsum... ... dolor sid amet Un autre paragraphe. Lorem ipsum... ... dolor sid amet Un autre paragraphe. ]]> Les éléments qui sont au même niveau doivent être séparés par une ligne vide pour améliorer la lisibilité. Lorem ipsum... Dolor sid amet... Lorem ipsum... Dolor sid amet... ]]> 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. ]]> 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. Paragraphe frère. ]]>< 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. ]]><> ]]><> ]]> La fermeture des éléments CDATA et <programlisting> devrait être sur la même ligne, sans aucune indentation. ]]><> ]]><> ]]><> ]]> 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". ]]>< ]]>< ]]>< 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>. <]]]]>> < ]]]]>> ]]> 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. Les short tags (e.g., "<?", "<?=") ne devrait jamais être utilisés dans l'élément programlisting ni dans le reste de la documentation. 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. La classe Zend_Class. ]]> 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. La variable $var et le membre de classe Zend_Class::$var. ]]> 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. La fonction foo() et la méthode Zend_Class::foo(). Une fonction avec une signature : foo($bar, $baz) ]]> 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. La constante FOO et la constante de classe Zend_Class::FOO. ]]> Les noms de fichier et chemins doivent être entourés par les balises <filename>. Aucun autre contenu n'est autorisé dans cet élément. Le nom de fichier application/Bootstrap.php. ]]> 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. Executez zf.sh create project pour créer un projet. ]]> L'utilisation de l'élément <code> est déconseillée, en faveur des autres éléments discutés précédement. L'élément <title> ne peut pas contenir d'éléments enfants. ]]> Pour éditer la documentation, vous ne devriez pas utiliser un éditeur XML 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 CDATA, remplacer 4 espaces par des tabulations, ou 2 espaces, etc. Ces recommandations ont été écrites en grande partie afin d'aider les traducteurs à déterminer les changements en utilisant la commande diff. Le formatage automatique rend cette opération plus difficile. 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 documentation/manual/en/figures/, et nommées juste après l'identifiant de la section qui les concerne. 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. Lorsque vous écrivez des exemples à inclure dans le manuel, suivez les conventions de codages ainsi que les recommandations pour la documentation. 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. Créez des liens vers les autres sections ou des ressources externes plutôt que de tout réécrire. Les liens vers d'autres sections du manuel peuvent se faire avec <link> (pour lequel vous devez fournir le nom du lien). "Link" crée un lien vers une section, et utilise un titre explicite : documentation sur la créer de liens. ]]> Pour créer un lien vers une ressource externe utilisez l'élément <ulink> : Le site du Zend Framework. ]]>