Contenu de référence de commandes complexes

Pour documenter des références de commandes complexes de logiciel, vous pouvez utiliser une combinaison d'éléments phrase DITA pour en décrire la syntaxe. Le balisage peut être adapté aux conventions de mise en forme syntaxique lors du processus de publication.

En rédaction basée sur le style, des conventions de mise en forme ont été utilisées pour identifier les éléments des commandes de syntaxes dédiés aux applications logicielles. Dans ce contexte, une commande est une chaîne de texte qu'un utilisateur saisit afin de lancer l'application et de lui passer des arguments.

Le Microsoft Manual of Style for Technical Publications suggère la syntaxe suivante :

  • commande en gras
  • un ensemble de choix entre accolades { }
  • choix individuels séparés par |
  • noms de variables en italique
  • arguments répétables signalés par ...
  • éléments optionnels entre crochets [ ] ou double crochets [[ ]].

Par exemple, une syntaxe de commande doit être représentée comme ant [-f filename] [-logfile filename] [-verbose].

Dans DITA, les éléments sémantiques suivants sont utilisés pour identifier les composants de la commande :
kwd
un mot clé textuel utilisé dans un fichier de commande, utilitaire ou batch
option
une option ou un changement qui modifie la commande
oper
un opérateur (tel que *, + ou =)
var
le nom d'une variable ou d'un argument
delim
un caractère de délimitation utilisé pour identifier le début ou la fin d'une partie de la syntaxe
sep
un caractère de séparation (une parenthèse par exemple) utilisé dans la syntaxe

Le balisage de la syntaxe devrait être considéré dans son ensemble au sein des éléments phrase de syntaxe (synph) ou bloc syntaxique (synblk).

Un exemple de ligne de commande balisée pourrait être : 
<synph>
 <kwd>ant</kwd> <option>-f</option> <var>filename</var>
 <option>-logfile</option> <var>filename</var>
 <option>-verbose</option>
</synph>

Une sortie typique de ce code serait :

ant -f filename -logfile filename -verbose

Lorsque cette syntaxe de commande est utilisée au sein d'une instruction destinée à un utilisateur (généralement dans une rubrique task), la syntaxe devrait au contraire être contenue dans un élément userinput, sans les éléments individuels de la commande sémantiquement identifiée.