Existe-t-il une norme pour écrire un synopsis de commande?

14

Il me semble que chacun a sa propre idée sur la façon d'écrire un synopsis décrivant l' utilisation des commandes pour l'utilisateur final.

Par exemple, c'est le format de man grep:

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

Maintenant, cela a une syntaxe qui apparaît dans d'autres pages de manuel. []est reconnu comme facultatif et a ...un sens en tant que multiple de la même entrée.

Mais les gens utilisent |ou /pour OR et il y en a d'autres qui inverseront ce que cela []signifie. Ou ils ne donnent aucune indication sur où [OPTIONS]va.

Je voudrais suivre une norme pour ce que j'écris, mais chaque site Web que je consulte me dit quelque chose de différent.

Existe-t-il une manière standard d'écrire des synopsis, ou la convention est-elle exactement ce que les gens ont fait au fil du temps?

command-line man Tormyst
la source
Choisissez en un et gardez le.
Kevin
Pour une raison quelconque, je ne pense pas que cela aiderait. Chaque personne aurait sa propre norme et rien ne serait jamais fait à ce sujet.
Tormyst
4
Est-ce le genre de norme que vous voulez dire? pubs.opengroup.org/onlinepubs/009695399/basedefs/…
Mark Plotnick
Oui, c'est exactement ce que je cherchais. Je vous remercie.
Tormyst
1
@MarkPlotnick - Je ferais de cela un A pour que le PO puisse l'accepter. C'est la norme si jamais il y en avait une. Référencez le lien référencé par illuminÉ.
slm

Réponses:

8

Le standard classique pour cela est de POSIX, Utility Argument Syntax (merci à @ illuminÉ pour le lien mis à jour). Il décrit la syntaxe à utiliser dans les pages de manuel, par exemple

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Étant classique, il recommande d'utiliser des options à un seul caractère, avec -Wune utilisation recommandée par les fournisseurs, et c'est ainsi que les options à plusieurs caractères sont prises en charge (voir, par exemple, le résumé des options de gcc ).

Le logiciel GNU a introduit des options multi-caractères qui commencent par --. Quelques directives de GNU pour formater les pages de manuel avec ces options peuvent être trouvées dans la référence help2man .

Mark Plotnick
la source