CmdSynopsis = ( ( Command | Arg | Group | SBR )+,
SynopFragment*
)
Arg = ( ( #PCDATA
| Arg
| Group
| Option
| SynopFragmentRef
| Replaceable
| SBR
)+
)
Group = ( ( Arg
| Group
| Option
| SynopFragmentRef
| Replaceable
| SBR
)+
)
SynopFragment = ( (Arg | Group )+
)
Option = (%smallcptr.char.mix;)*
|
Éléments : CmdSynopsis, Command, Arg, Group, SBR, Option, SynopFragmentRef, Replaceable. Attributs : Sepchar, CmdLength, Choice, Rep.
L'élément CmdSynopsis permet de donner la définition, ou synopsis, d'une commande logicielle.
Il n'est pas nécessaire de fournir la ponctuation et la mise en page pour le rendu final de la définition de la commande. Néanmoins, il est des situations où le système de traitement n'arrivera pas à fournir de présentation convenable. Un élément SBR est fourni pour aider le traitement. Cet élément indique de placer un retour à la ligne dans la définition de la commande. Cet élément peut être placé à tout niveau dans l'élément CmdSynopsis, sauf directement dans l'élément SynopFragment.
Un synopsis de commande est composé d'une première partie donnant le nom de la commande, la liste des ses options et de ses paramètres. Si cette liste est trop longue, il est possible de raccourcir cette première partie et d'en créer une seconde, contenant des fragments de synopsis (SynopFragment), et qui seront référencés à partir de la première partie à l'aide d'éléments SynopFragmentRef.
Il est possible de spécifier, grâce à l'attribut Sepchar, le caractère séparant la commande de tous les arguments de plus haut niveau lors du rendu de la définition.
L'attribut CmdLength permet de spécifier sur quelle largeur de page sera rendue la définition de commande. Le système de formatage pourra utiliser cette valeur pour couper une définition de commande en plusieurs lignes.
La première partie est composée d'un ou plusieurs des éléments suivants, dans un ordre quelconque :
un nom de commande (Command),
un argument (Arg),
un groupe d'arguments (Group),
un retour à la ligne (SBR).
La commande nommée grâce à l'élément Command est la commande à définir. Son nom apparaîtra généralement au début du synopsis.
Un élément Arg peut représenter aussi bien une option de la commande (par exemple -l /l) qu'un paramètre de la commande (par exemple main.c). Mais il peut aussi représenter une option suivie d'un ou plusieurs paramètres, comme -p 1-10.
Un groupe Group permet de regouper plusieurs options ou paramètres afin de préciser qu'ils s'excluent mutuellement. L'utilisateur doit choisir une option ou un paramètre parmi le groupe d'options ou de paramètres.
Il est possible d'indiquer qu'un argument défini par Arg ou qu'un groupe défini par Group peut être répété ou non, grâce à l'attribut Rep. Si l'argument ou groupe peut être répété, on lui donnera la valeur Repeat. Au contraire, si l'argument ou groupe ne peut pas être répété, on lui donnera la valeur Norepeat, ou on omettra cet attribut, qui prend la valeur Norepeat par défaut. Un argument ou groupe pouvant être répété sera généralement représenté suivi d'une ellipse (...).
Il est aussi possible d'indiquer qu'un argument ou groupe est soit optionnel, soit requis. Pour un groupe, il est possible d'indiquer si l'utilisateur doit choisir un nombre quelconque ou bien un ou plusieurs éléments. Pour cela, il faut utiliser l'attribut Choice. Si l'argument ou groupe est optionnel, on lui donnera la valeur Opt, ou on omettra l'attribut, qui prend cette valeur par défaut. Si l'argument ou groupe est requis, on utilisera la valeur Plain, ou la valeur Req pour insister sur le caractère requis de l'argument ou groupe. Pour indiquer à l'utilisateur qu'il peut choisir un nombre quelconque d'éléments du groupe, on utilisera la valeur Optmult, et pour lui indiquer qu'il doit choisir au moins un élément, la valeur Reqmult.
Un argument Arg peut à son tour contenir un ou plusieurs des éléments suivants, dans un ordre quelconque :
des caractères,
un argument (Arg),
un groupe d'arguments (Group),
une option
une référence vers un fragment de synopsis (SynopFragmentRef),
un élément remplaçable (Replaceable),
un retour à la ligne (SBR).
Le texte donnera l'argument lui-même. Par exemple, <Arg>-l</Arg> représente l'option -l d'une commande.
L'utilisation de certaines options ou paramètres d'une commande entraîne la possibilité d'utiliser d'autres options ou paramètres. Par exemple, l'option -w de la commande ls nécessite un paramètre cols. Autre exemple, l'utilisation du paramètre host de telnet rend possible l'utilisation du paramètre port. Par contre, le second n'est pas utilisable sans l'utilisation du premier.
Pour ce genre de situations, on utilisera l'imbrication des arguments Arg. Le premier exemple s'écrira :
<cmdsynopsis> <command>ls</command> <arg choice="opt">-l <arg choice="plain"><replaceable>col</replaceable ></arg></arg> </cmdsynopsis> |
et le second exemple :
<cmdsynopsis> <command>telnet</command> <arg choice="opt"><replaceable>host</replaceable ><arg choice="opt"><replaceable>port</replaceable></arg></arg> </cmdsynopsis> |
Un groupe d'arguments Group peut, lui, contenir un ou plusieurs des éléments suivants, dans un ordre quelconque :
un argument (Arg),
un groupe d'arguments (Group),
une option (Option),
une référence vers un fragment de synopsis (SynopFragmentRef),
un élément remplaçable (Replaceable),
un retour à la ligne (SBR).
Certaines options peuvent être complétées par une valeur, prise parmi un certain nombre de valeurs données. Par exemple, l'option --color de la commande ls peut être suivie d'un signe = et d'un des mots-clés none, auto ou always. auto or always.
Pour ce genre de situation, on utilisera un groupe Group à l'intérieur d'un argument Arg. En voici un exemple d'utilisation :
<cmdsynopsis>
<command>ls</command>
<arg>--time<arg choice="plain">=<group choice="req">
<arg>atime</arg>
<arg>access</arg>
<arg>use</arg>
<arg>ctime</arg>
<arg>status</arg>
</group>
</arg></arg><sbr>
<arg>--color<arg>=<group choice="req">
<arg>none</arg>
<arg>auto</arg>
<arg>always</arg>
</group>
</arg></arg>
</cmdsynopsis>
|
La seconde partie d'un synopsis de commande peut être constitué d'un nombre quelconque de fragments de synopsis (SynopFragment). Un fragment de synopsis permet de retirer un ensemble d'options ayant une relation entre elles du corps du synopsis et de les placer à la suite de celui-ci. Ceci permet de simplifier la lecture du synopsis.
Utilisez une référence à un fragment de synopsis (SynopFragmentRef) pour indiquer, dans le synopsis, un lien vers un fragment de synopsis.
Un fragment de synopsis (SynopFragment) peut contenir un ou plusieurs arguments (Arg) ou groupes (Group), dans un ordre quelconque. arguments (Arg) or groups (Group), in any order.
<cmdsynopsis>
<command>gcc</command>
<arg><synopfragmentref linkend="overall"
>overall options</synopfragmentref></arg>
<arg><replaceable>filename</replaceable></arg>
<synopfragment id="overall">
<arg>-c</arg>
<arg>-S</arg>
<arg>-E</arg>
<arg>-o <replaceable>file</replaceable></arg>
<arg>-pipe</arg>
<arg>-v</arg>
<arg>-x <replaceable>language</replaceable></arg>
</synopfragment>
</cmdsynopsis>
|
| Précédent | Sommaire | Suivant |
| Synopsis | Niveau supérieur | Synopsis de fonction |