Décrire la syntaxe

Rédiger des références et des glossaires DITA Leçon 1 : Créer une référence Décrire la syntaxe
Progression de la Leçon
0% Terminé

La description syntaxique est une composante cruciale d’une référence API ou d’une référence de ligne de commande. Elle indique les options ou formes possibles de chaque appel de commande ou de fonction.

Un diagramme syntaxique utilise une sténographie textuelle ou graphique pour représenter les mots clés, les caractères de remplissage (variables) et les autres caractères nécessaires à une commande ou à un appel de fonction. Les diagrammes syntaxiques textuels utilisent généralement des crochets [], des accolades {} et des barres | pour indiquer les parties de syntaxe facultatives ou obligatoires. Les diagrammes syntaxiques graphiques utilisent des lignes et des flèches pour représenter les parties optionnelles, répétées et obligatoires de la syntaxe. Pour une illustration des diagrammes syntaxiques graphiques, voir cette page Wikipedia.

Comme la description de la syntaxe est fréquemment requise dans les références, la spécialisation des références fournit l’élément <refsyn> pour contenir la syntaxe de la commande.

L’élément <refsyn> est spécialisé à partir de l’élément <section> et peut contenir tous les éléments autorisés dans l’élément <section>, y compris l’élément <title>.

Il y a plusieurs façons d’ajouter le diagramme syntaxique réel à l’élément <refsyn>, comme par exemple :

  • Utiliser les éléments <image> ou <fig> pour inclure une image du diagramme de syntaxe (généralement non recommandé)

  • Utiliser les éléments <codeblock> ou <pre> (préformatté) pour créer un diagramme de syntaxe textuel (acceptable, mais n’autorise que très peu de balises supplémentaires)

  • Uiliser l’élément <synph> (phrase syntaxique) pour créer un diagramme de syntaxe textuel (illustré dans cette leçon)

  • Utiliser l’élément <syntaxdiagram>, qui utilise des éléments supplémentaires pour décrire les parties et les relations dans un diagramme de syntaxe. Ces éléments peuvent apparaître de nombreuses façons, selon la façon dont vous générez votre publication. Cependant, il n’y a pas d’éditeur visuel disponible pour les éléments <syntaxdiagram>, ce qui peut rendre leur utilisation difficile.

Pour en savoir plus sur les avantages et les inconvénients de l’utilisation des éléments <synph> et <syntaxdiagram>, se référer à l’article de Simon Bate sur la compréhension des diagrammes dans DITA.

Pratique
  1. Continuez d’utiliser l_reference_debut.dita.
  2. Aprés l’élément <section>, ajoutez un élément <refsyn>. 
       <title>tNav</title>
   <refbody>
     <section><p>La commande <cmdname>tNav</cmdname> est utilisée dans la
     base de données Canard pour naviguer vers une table ou une vue différente.</p></section>
     <refsyn>
     
     </refsyn>
   </refbody> 
</reference>

  3. À l’intérieur de l’élément <refsyn>, ajoutez un élément <synph> (phrase de syntaxe) pour contenir l’exemple de la commande et ajoutez-y du contenu tel que présenté ici : 
       <title>tNav</title>
   <refbody>
     <section><p>La commande <cmdname>tNav</cmdname> est utilisée dans la
     base de données Canard pour naviguer vers une table ou une vue différente.</p></section>
     <refsyn>
         <synph>
             -tNav tNom [tVue]
         </synph>
     </refsyn>
   </refbody> 
</reference>

  4. Balisez la chaîne « tNom » à l’intérieur de l’élément <synph> avec l’élément <var> (variable).
    L’élément <var> identifie la chaîne comme une variable ou un caractère de remplissage dans la syntaxe. Dans la plupart des publications générées, cela sera rendu en italique. 
       <title>tNav</title>
   <refbody>
     <section><p>La commande <cmdname>tNav</cmdname> est utilisée dans la
     base de données Canard pour naviguer vers une table ou une vue différente.</p></section>
     <refsyn>
         <synph>
             -tNav <var>tNom</var> [tVue]
         </synph>
     </refsyn>
   </refbody> 
</reference>

Contributeurs
Chapitre précédent
Retour à la Leçon
Chapitre suivant