Format des fichiers de documentationBalises XMLChaque 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.
Longueur maximum d'une ligneLa 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. IndentationL'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.
Fin de ligneLes 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 videsLes éléments vides ne sont pas autorisés, tous les éléments doivent contenir du texte ou des éléments enfants.
Utilisation des espaces dans les documentsEspace entre les balisesLes 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).
Les balises ouvrantes des éléments en-ligne ne devrait pas être suivi d'espace.
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.
Sauts de ligne multiplesLes sauts de ligne multiples ne sont pas autorisés ni dans les balises, ni entre elles.
Séparation entre les balisesLes éléments qui sont au même niveau doivent être séparés par une ligne vide pour améliorer la lisibilité.
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.
Exemple de codeLa 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.
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.
Notes spécifiques sur les éléments en-ligneclassnameL'é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.
varnameLes 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.
methodnameLes 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.
constantUtilisez 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.
filenameLes noms de fichier et chemins doivent être entourés par les balises <filename>. Aucun autre contenu n'est autorisé dans cet élément.
commandLes 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.
codeL'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 bloctitleL'élément <title> ne peut pas contenir d'éléments enfants.
|