| Écrire de la documentation en utilisant DocBook: Un cours accéléré | ||
|---|---|---|
| Précédent | Chapitre 10. Description de l'interface d'une application | Suivant |
Les balises suivantes sont utilisées pour désigner les éléments d'une commande:
| type - Classification d'une valeur |
| literal - Chaîne littérale, utilisée dans le corps du texte, qui est une partie de donnée dans un ordinateur |
| userinput - Donnée saisie par l'utilisateur |
| symbol - Nom remplacé par une valeur avant l'exécution |
| replaceable - Contenu pouvant être remplacé dans un sommaire ou une ligne de commande |
| filename - Nom d'un fichier, avec possibilité de préciser le chemin |
| prompt - Caractère indiquant le début d'un champ saisi |
| paramdef - Information sur le type de donnée et le nom du paramètre qui s'applique à cette information |
| parameter - Partie d'une instruction à un ordinateur |
| option - Option pour une commande de programme d'ordinateur |
| envar - Variable d'environnement |
| command - Programme exécutable ou la saisie effectuée par l'utilisateur pour exécuter une commande |
| cmdsynopsis - Sommaire d'une commande |
| arg - Argument dans cmdsynopsis |
| computeroutput - Donnée présentée à l'utilisateur par l'ordinateur |
| funcsynopsis - Syntaxe de sommaire pour une définition de fonction |
| funcsynopsisinfo - Information générale sur l'utilisation de la fonction |
| funcprototype - Prototype de la fonction |
| funcdef - Nom et valeur de retour de la fonction |
| function - Nom de la fonction |
| paramdef - Nom et type du paramètre d'une fonction |
| parameter - Nom du paramètre d'une fonction |
Il existe deux situations dans lesquelles vous pouvez vouloir décrire une commande : montrer un exemple d'un type de ligne de commande et une description détaillée de tous les arguments et options d'une commande comme vous pouvez le voir dans les pages de manuel.
DocBook gère ces deux contextes avec les balises <command> et <cmdsynopsis>.
Exemple 10-6. Une commande et sa sortie
<screen> <prompt>bash$</prompt> <command>tourneboule -c 1 <replaceable>monfichier</replaceable> </command> tourneboulage de monfichier.....accompli ! </screen>
bash$ tourneboule -c 1 monfichier tourneboulage de monfichier.....accompli !
La balise command peut également être utilisée à l'intérieur d'un paragraphe pour baliser le nom d'une commande. Par exemple :
The <command>twiddle</command> command is used to twiddle files. Twiddled files will be marked with the .twid extension, so if I <command>twiddle</command> <replaceable>myfile</replaceable> then it will become <replaceable>myfile.twid</replaceable>. Errors are written to the file <filename>twiddle.err</filename>.
La balise <prompt> est utilisée pour désigner l'invite de commande d'une ligne de commande. Replaceable désigne le texte qui sera remplacé par l'utilisateur. Dans l'exemple, myfile est juste un nom arbitraire pour un fichier car nous ne connaissons pas le nom du fichier, nous voulons simplement montrer comment fonctionne la commande. Si un nom de fichier dans une commande est connu, nous utilisons la balise <filename> à la place.
Baliser une cmdsynopsis est un peu plus difficile. Ici un exemple tiré de la Référence DocBook :
Exemple 10-7. Une commandsynopsis
<cmdsynopsis>
<!-- This is a synopsis for the command foo.
The options -a and -x are optional and exclusive
The option -c takes a cheese and is optional and repeatable
The options -t and -k are referred to in another fragment
The options -i, -j, and -k are required and exclusive
The option -f takes a filename and is required
The -t and -k options specify the kind of milk and mold in an
optional and repeatable group
-->
<command>foo</command>
<group>
<arg>-a</arg>
<arg>-x</arg>
</group>
<group>
<arg rep="repeat">-c <replaceable>cheese</replaceable></arg>
<synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref>
</group>
<group choice="req">
<arg>-i</arg>
<arg>-j</arg>
<arg>-k</arg>
</group>
<arg choice="req">-f <replaceable>filename</replaceable></arg>
<synopfragment id="cheesetype">
<group rep="repeat">
<arg>-t <replaceable>milk</replaceable></arg>
<arg>-k <replaceable>mold</replaceable></arg>
</group>
</synopfragment>
</cmdsynopsis>
foo [-a | -x] [-c cheese(1)cheesetype] {-i | -j | -k} {-f filename}
(1) [-t milk | -k mold]...
Une cmdsynopsis contient une commande, des groupes d'arguments relatifs, des arguments indépendants et synopfragments. Le <arg> désigne les arguments de la commande. arg a deux attributs : choice et rep. choice est utilisé pour indiquer soit que la balise est optionnelle (par défaut), requise (req), soit qu'elle sera affichée sans aucune décoration (plain). La balise <group> sert à grouper les args relatifs. synopfragment est la plus compliquée des balises cmdsysopsis. Elle est utilisée pour fournir une description plus détaillée des options d'un argument. Une synopfragment consiste en deux parties : le synopfragment, qui contient les Args additionnels et la synopfragmentref qui pointe vers la description détaillée.
| Précédent | Sommaire | Suivant |
| Éléments d'interface GUI | Niveau supérieur | Description d'une API |