Éléments de référence

4. Éléments de référence

Utilisez les éléments de référence pour décrire les caractéristiques régulières d'ensembles de choses, le plus souvent les commandes dans un langage de programmation. Toutefois, ce format convient aussi pour les recettes, les bibliographies, les catalogues et collections similaires de descriptions structurées. Pour plus de détails sur l'utilisation de l'élément <reference> et des autres types d'information, veuillez consulter la spécification architecturale DITA.

4.1. reference
L'élément <reference> définit le conteneur de niveau supérieur d'un thème de référence. Les thèmes de référence documentent des structures de programmation ou des faits à propos d'un produit. Des exemples comprennent les éléments de langage, les descriptions de classe, les commandes, les fonctions, les déclarations, les protocoles, les types, les déclarateurs, les opérandes et les informations d'interface de programmation (API), qui fournissent un accès rapide aux faits mais aucune explication des concepts ou des procédures. Les thèmes de référence ont la même structure de niveau supérieur que tout autre type de thème, avec un titre, une description courte et un corps. Pour le corps, les thèmes de référence sont typiquement organisés en une ou plusieurs sections, listes de propriétés et tables. Le type de thème reference fournit des règles générales qui s'appliquent à toutes sortes d'informations de référence, en utilisant des éléments tels que <refsyn> pour la syntaxe ou les signatures, et <properties> pour les listes et les valeurs.

4.2. refbody
L'élément <refbody> est un réceptacle pour le contenu principal du thème de référence. Les thèmes de référence limitent la structure du corps aux tables (à la fois simples et standards), aux listes de propriétés, aux sections de syntaxe, et aux sections et exemples génériques, dans n'importe quel ordre ou nombre.

4.3. refsyn
L'élément <refsyn> est une section spéciale dans un thème de référence. La section contient souvent de la syntaxe ou une signature (par exemple, la syntaxe d'appel d'un utilitaire en ligne de commande, ou la signature d'une interface de programmation API). L'élément <refsyn> contient une description brève éventuellement schématique de l'interface ou de la structure de niveau supérieur du sujet.

4.4. properties
L'élément <properties> donne une liste de propriétés pour le sujet du thème courant, par exemple si une classe est publique ou protégée. Chaque propriété peut inclure le type, la valeur et une description. Le rendu typique est habituellement un format de type table. Pour représenter les valeurs multiples d'un type, créez juste des éléments de propriété supplémentaires et utilisez seulement l'élément <propvalue> (et <propdesc> si besoin) pour chaque valeur successive.

4.5. prophead
L'élément <prophead> porte les titres réguliers de l'élément <properties>.

4.6. proptypehd
L'élément <proptypehd> porte les titres réguliers de la colonne de type d'une table <properties>.

4.7. propvaluehd
L'élément <propvaluehd> porte les titres réguliers de la colonne de valeur d'une table <properties>.

4.8. propdeschd
L'élément <propdeschd> porte les titres réguliers de la colonne de description d'une table <properties>.

4.9. property
L'élément <property> représente une propriété du sujet du thème courant. Par exemple, si le thème courant est une classe, la propriété pourrait montrer que la classe est protégée au lieu de publique. Il contient trois éléments optionnels : <type>, <value> et <description>.

4.10. proptype
L'élément <proptype> décrit le type de propriété.

4.11. propvalue
L'élément <propvalue> indique la valeur ou les valeurs du type de la propriété courante. On peut placer les valeurs dans des rangées séparées si elles ont besoin de descriptions séparées, et simplement laisser l'élément <proptype> blanc.

4.12. propdesc
L'élément <propdesc> est utilisé pour fournir une description courte du type de la propriété et ses valeurs listées (ou juste la valeur).

Section précédente 3. Éléments de concept

Section suivante 5. Éléments de tâche

Retour au sommaire.