Dans la plupart des références d’une API ou d’une ligne de commande, le diagramme syntaxique est immédiatement suivi d’une liste ou d’un tableau qui décrit en détail les différents mots clés, caractères de remplissage et autres options. Le diagramme syntaxique indique au lecteur où ces objets sont utilisés ; le tableau des propriétés fournit des informations sur les raisons pour lesquelles le lecteur utiliserait ces objets.
Par exemple, dans une commande d’exportation de graphiques, le paramètre filetype pourrait autoriser les valeurs « gif », « png », « bmp » et « svg » ; vous pourriez vouloir donner des informations spécifiques sur les implications de l’utilisation de chacun des types de fichiers.
Dans la rubrique DITA de type référence, l’élément <properties> fournit une façon de structurer ces informations. L’élément <properties> est l’un des éléments que vous pouvez utiliser dans un élément <refbody>.
L’élément <properties> contient un ou plusieurs éléments <property>, chacun décrivant une seule propriété. L’élément <property> peut contenir des éléments pour le type (<proptype>), la valeur (<propvalue>), et la description (<propdesc>). Pour une utilisation courante, ceux-ci peuvent contenir :
| Type de document |
<proptype> |
<propvalue> |
<propdesc> |
| Référence d’une ligne de commande |
Paramètre de commande |
Valeur ou mot-clé autorisé pour le paramètre |
Description du paramètre (sa signification, ce que son utilisation implique) |
| Référence API |
Argument de fonction |
Type de données de l’argument ou type d’objet |
Description de l’argument et de son effet sur l’API |
| Référence de la base de données |
Nom du champ ou de la colonne de la base de données |
Type de données |
Description du contenu |
Dans le cas d’un paramètre de commande (<proptype>) qui comporte plusieurs mots-clés, vous pouvez créer un élément de type <property> avec des éléments de type <proptype>, <propvalue>, et <propdesc> pour le premier mot-clé. Ensuite, pour les mots-clés suivants, créez des éléments supplémentaires de type <property> qui ne contiennent que des éléments de type <propvalue> et <propdesc>.
L’élément <properties> est une spécialisation de l’élément <simpletable> et est souvent publié sous forme de tableau. Si nécessaire, vous pouvez créer des têtes de colonne pour les colonnes type, valeur et description en utilisant un élément <prophead> contenant les éléments <proptypehd>, <propvaluehd> et <propdeschd>.
Vidéo : Créer une table propriétés DITA
Pratique
- Continuez d’utiliser l_reference_debut.dita.
- Après l’élément <refsyn>, ajoutez un élément <properties> et ajoutez un élément <prophead> à l’intérieur.
...
</refsyn>
<properties>
<prophead>
</prophead>
</properties>
</refbody>
</reference>
- À l’intérieur de l’élément <prophead>, ajoutez les éléments <proptypehd>, <propvaluehd> et <propdeschd> et ajoutez-y du contenu tel que présenté ici :
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="ma_premiere_ref">
<title>tNav</title>
<refbody>
...
</refsyn>
<properties>
<prophead>
<proptypehd>Type</proptypehd>
<propvaluehd>Nom</propvaluehd>
<propdeschd>Description</propdeschd>
</prophead>
</properties>
</refbody>
</reference>
Remarque :
Bien qu’ils ne soient pas tous requis, les éléments ajoutés ici doivent être dans cet ordre précis. S’ils ne le sont pas, votre document ne sera pas validé.
- Après l’élément <prophead>, ajoutez un élément <property>.
...
</refsyn>
<properties>
<prophead>
<proptypehd>Type</proptypehd>
<propvaluehd>Nom</propvaluehd>
<propdeschd>Description</propdeschd>
</prophead>
<property>
</property>
</properties>
</refbody>
</reference>
- À l’intérieur de l’élément <property>, ajoutez les éléments <proptype>, <propvalue> et <propdesc> et ajoutez-y du contenu tel que présenté ici :
...
</refsyn>
<properties>
<prophead>
<proptypehd>Type</proptypehd>
<propvaluehd>Nom</propvaluehd>
<propdeschd>Description</propdeschd>
</prophead>
<property>
<proptype>Table</proptype>
<propvalue>dbo.DBBL</propvalue>
<propdesc>Canards de Barbarie</propdesc>
</property>
</properties>
</refbody>
</reference>
Remarque :
Si vous omettez l’une des en-têtes, vous devez également omettre l’élément de propriété associé. Par exemple, si votre élément <prophead> ne contient pas d’élément <propdeschd>, vous devez omettre l’élément <propdesc> dans vos éléments <property>.
- Ajoutez des éléments <property> et ajoutez-y du contenu tel que présenté ici :
...
</refsyn>
<properties>
<prophead>
<proptypehd>Type</proptypehd>
<propvaluehd>Nom</propvaluehd>
<propdeschd>Description</propdeschd>
</prophead>
<property>
<proptype>Table</proptype>
<propvalue>dbo.DBBL</propvalue>
<propdesc>Canards de Barbarie</propdesc>
</property>
<property>
<proptype></proptype>
<propvalue>dbo.DVNG</propvalue>
<propdesc>Canards plongeurs</propdesc>
</property>
<property>
<proptype></proptype>
<propvalue>dbo.WHST</propvalue>
<propdesc>Canards siffleurs</propdesc>
</property>
<property>
<proptype>Vue</proptype>
<propvalue>regn.ne</propvalue>
<propdesc>Canards situés principalement dans le nord-est</propdesc>
</property>
<property>
<proptype></proptype>
<propvalue>regn.se</propvalue>
<propdesc>Canards situés principalement dans le sud-est</propdesc>
</property>
<property>
<proptype></proptype>
<propvalue>pttrn.migr</propvalue>
<propdesc>Canards organisés selon leur mode de migration</propdesc>
</property>
</properties>
</refbody>
</reference>
Pratique
Ouvrez le fichier leçon1/l_reference_exercice_debut.dita et utilisez-le pour convertir le contenu suivant en DITA :
ajouteEntree
La commande ajouteEntree est utilisée pour entrer une nouvelle version de la documentation dans la base de données d’analyse du contenu.
-ajouteEntree {nLangage | nVersion | nSortie}
| Requis ? |
Paramètre |
Description |
| Oui |
nLangage |
La langue affichée par défaut |
|
nVersion |
La version du contenu affichée par défaut |
|
nSortie |
Le format de livraison requis |
Contributeurs
