3.1.8. Référence

Les thèmes de référence décrivent les caractéristiques régulières d'un sujet ou d'un produit, telles que les commandes dans un langage de programmation.

Pourquoi les références ?

Dans la documentation technique, les thèmes de référence sont souvent utilisés pour couvrir des sujets tels que les commandes dans un langage de programmation. Les thèmes de référence peuvent inclure tout ce qui a un contenu régulier, tels que les ingrédients d'une recette de cuisine, les listes bibliographiques, les catalogues et similaires. Les thèmes de référence fournissent un accès rapide aux faits. L'information nécessaire pour une compréhension approfondie d'un thème de référence ou pour effectuer des procédures liées devrait être fournie dans un thème de concept ou de tâche.

Structure des références

L'élément <reference> est l'élément supérieur d'un thème de référence. Chaque thème de référence contient un élément <title> et un élément <refbody>, et les éléments optionnels <titlealts>, <shortdesc> ou <abstract>, <prolog>, <related-links>, et des thèmes imbriqués.

L'élément <refbody> recèle le contenu principal du thème de référence. Les thèmes de référence limitent la structure du corps à des tables (simples et standards), des listes de propriétés, des sections de syntaxe et des sections génériques, et des exemples.

Tous les sous-éléments de <refbody> sont optionnels et peuvent apparaître en ordre et en nombre quelconques.

section: Représente une division structurelle dans un thème de référence. Les sections structurent des sous-ensembles d'information au sein d'un thème plus grand. On ne peut inclure qu'une liste simple de sections de même niveau (peer sections) dans un thème ; les sections ne peuvent pas être imbriquées. Une section peut avoir un titre optionnel.
refsyn: Contient une 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 courte éventuellement schématique de l'interface ou de la structure de niveau supérieur du sujet.
example: Fournit des exemples qui illustrent ou soutiennent le thème courant. L'élément <example> a le même modèle de contenu que l'élément <section>.
table: Organise l'information en une structure tabulaire de rangées et colonnes. Le balisage du tableau offre également des structures plus complexes, dont le recouvrement (spanning) des rangées et des colonnes, ainsi que les légendes (table captions).
simpletable: Contient l'information en rangées et colonnes ordinaires et n'offre pas de légende.
properties: Liste des propriétés et leurs types, valeurs et descriptions.

Voici un exemple de thème de référence :

<reference id="boldproperty">
<title>Bold property</title>
<shortdesc>(Read-write) Whether to use a bold font for the specified
text string.</shortdesc>
<refbody>
  <refsyn>
    <synph>
      <var>object</var><delim>.</delim><kwd>Font</kwd><delim>.</delim>
      <kwd>Bold</kwd><delim> = </delim><var>trueorfalse</var>
    </synph>
  </refsyn>
  <properties>
    <property>
      <proptype>Data type</proptype>
      <propvalue>Boolean</propvalue>
    </property>
    <property>
      <proptype>Legal values</proptype>
      <propvalue>True (1) or False (0)</propvalue>
    </property>
  </properties>
</refbody>
</reference>

Modules

reference.mod (DTD) ;
referenceMod.xsd, referenceGrp.xsd (schéma).

Section parente 3.1. Thèmes DITA

Section précédente 3.1.7. Tâches

Section suivante 3.1.9. Glossaire

Retour au sommaire.