Noms de paramètres et de variables

DITA compte quatre éléments permettant de différencier paramètres, arguments et variables en fonction du contexte dans lesquels ils sont utilisés.

En informatique, un paramètre est un type de variable passé à un programme ou à une sous-routine. Le terme paramètre est étroitement lié à la notion d'argument : un paramètre est directement défini dans la définition de la procédure, alors que l'argument est la valeur passée à la procédure, définie dans l'appel de la procédure. (Ici, le terme procédure représente une fonction d'un programme, d'une routine ou d'une sous-routine.)

Par exemple, dans la procédure CalcCharge ci-dessous, les paramètres définis sont tauxHeure et nbHeures.

Function CalcCharge(tauxHeure as Integer, nbHeures as Integer) as Integer
  Return (tauxHeure * nbHeures)
End Function

Lorsque la procédure CalcCharge est appelée, les arguments prennent les valeurs passées à la procédure ; dans cet exemple, les valeurs sont 55 et 130.

prixbrut = CalcCharge(55,130)

Dans certains cas, les valeurs des variables deviennent des arguments ; ainsi, chaque valeur se verra attribuer une chaîne de texte.

hr = 55
co = 130
prixbrut = CalcCharge(hr,co)

Les trois termes paramètre, argument et variable sont souvent utilisés comme synonymes, à tel point que leurs réelles significations sont souvent confondues. Pour ajouter à la confusion, leurs significations dans le domaine de la documentation sont légèrement différentes. Par exemple, une variable est utilisée en documentation pour désigner un conteneur que le lecteur doit modifier par les valeurs qu'il aura choisies.

DITA compte quatre éléments utilisables pour identifier paramètres, arguments, et variables : parmname (nom de paramètre), parml (liste de paramètres), varname (nom de variable) et var (variable).

parmname: Utilisé pour identifier les paramètres de programmation et les arguments présents dans les commandes, les appels et les fonctions. La documentation se concentre plus généralement sur les paramètres (c'est-à-dire les informations passées dans la procédure) davantage que sur les arguments de la procédure. Avoir appelé cet élément parmname est donc judicieux. Dans DITA, l'élément parmname appartient au domaine Programmation ; il est davantage prévu pour la documentation des API que pour la documentation des applications.
parml: Utilisé pour identifier une liste de paramètres de programmation et d'arguments présents dans les commandes, les appels et les fonctions. L'élément parml suit une structure de liste composée des éléments plentry (ligne), pt (terme de paramètre) et pd (définition de paramètre). Dans DITA, l'élément parmname appartient au domaine Programmation ; il est davantage prévu pour la documentation des API que pour la documentation des applications.
varname: Utilisé lorsque le lecteur doit personnaliser une valeur en fonction de son contexte et de son environnement. Par exemple, dans une procédure de connexion à un système, le nom d'utilisateur (qui est différent pour chaque utilisateur) est balisé en tant que <varname>. Dans DITA, l'élément varname appartient au domaine Software ; il est prévu pour la documentation des applications logicielles.
var: Utilisé uniquement dans des diagrammes de syntaxe (syntaxdiagram), qui sont des représentations spécifiques utilisées pour documenter les langages de programmation et les interfaces de programmation d'application (API). Dans DITA, l'élément var appartient au domaine Programmation ; il est davantage prévu pour la documentation des API que pour la documentation des applications.

Si on veut documenter la fonction CalcCharge utilisée en exemple, on peut adopter l'approche suivante :

<p>La fonction <apiname>CalcCharge</apiname> compte deux paramètres :
 <parml>
   <plentry>
    <pt>taux</pt>
    <pd>Le taux horaire imposé au client.</pd>
   </plentry>
   <plentry>
    <pt>heures</pt>
    <pd>Le nombre d'heures totales passées sur le projet du client.</pd>
   </plentry>
 </parml>
</p>
<p>Les deux paramètres <parmname>taux</parmname> et <parmname>heures</parmname> doivent être des nombres entiers.
</p>

En revanche, l'élément varname peut être utilisé pour décrire le code VIN (numéro d'identification du véhicule) dans le manuel du propriétaire d'une voiture ; comme le montre cet exemple :

<p>Le code VIN est composé à partir des éléments suivants :
 <varname>Lieu de fabrication</varname>
 <varname>Modèle</varname>
 <varname>Marque</varname>
 <varname>Moteur</varname>
 <varname>Type</varname>
 <varname>Équipement</varname>
 <varname>Chiffre de contrôle</varname>
 <varname>Année de fabrication</varname>
 <varname>Numéro de fabrication</varname>
</p>

Dans le manuel d'utilisation d'un logiciel, l'élément varname peut être utilisé lorsqu'on souhaite décrire l'emplacement d'un répertoire, par exemple :

<p>Le fichier de transfert est généré par l'application <cmdname>Build</cmdname>et 
enregistré dans <filepath><varname>Mes Documents</varname>\acme\xfer</filepath>.</p>

Pour résumer, utilisez l'élément parmname pour programmer variables, paramètres et arguments, et l'élément varname pour tout autre emplacement des variables de documentation.

N'utilisez pas de crochets ou autres conventions syntaxiques pour nommer des variables simples. Si votre outil de publication ne permet pas d'insérer ces conventions durant le traitement, il serait alors nécessaire de le configurer.