Cours DocBook accelere

10.3. Éléments de ligne de commande

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> 
Qui apparaîtra comme :

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 commande twiddle est utilisée pour manier les fichiers. Les fichiers manipulés seront marqués avec l'extension .twid, ainsi si je fais twiddle myfile il deviendra myfile.twid. Les erreurs sont écrites dans le fichier twiddle.err".

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>
 
Qui donnera ceci :

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.