Le synopsis d'une commande permet de savoir d'un seul coup d'œil quels sont ses arguments. Il y a plusieurs moyen de décrire cela, c'est pour cette raison que nous imposons cette convention ici.
Pour la commande gg, qui prend un argument facultatif nommé « lang » avec une valeur par défaut « fr » et des termes de recherche sous forme d'arguments non nommés, donc voici un exemple d'exécution :
gg lang:en vaches à lait
Aurait pour synopsis ceci :
[lang:fr] <terme de recherche,>
Les crochets déterminent la facultativité d'un argument. Les arguments nommés étant de fait facultatif, il faudra toujours employer les crochets pour les décrire.
Les chevrons sont utilisés sur les arguments non nommés. La virgule avant le chevron de fermeture indique que l'on peut écrire plusieurs fois cet argument (dans le cas ci-dessus, il peut y avoir plusieurs termes de recherches).
La valeur après les deux-points correspond à la valeur par défaut de l'argument.
Si le synopsis est vraiment très long, il est possible de regrouper les arguments dans un seul terme, et de les expliquer plus en détail dans la description. Par exemple, au lieu d'écrire :
[lang:fr] [site:image] [codage:utf8] [type:recherche] [nbrpp:20] [date:today] <terme de recherche,>
Il est préférable d'écrire :
[*OPTIONS*] <terme de recherche,>
Les explications sur chaque option étant dans la description.
Il est aussi possible de mixer les arguments groupés et non groupés, séparer les groupes... En fait, tout est à l'appréciation du contributeur de la commande, le but étant que le synopsis soir clair et conci.
N'hésitez pas à jeter un coup d'oeil aux autres commandes pour voir comment sont écrits leurs synopsis.
