Existe-t-il un format «standard» pour le texte d'aide en ligne de commande / shell?

239

Sinon, existe-t-il une norme de facto? Fondamentalement, j'écris un texte d'aide en ligne de commande comme ceci:

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

Je l'ai fait en lisant simplement le texte d'aide de divers outils, mais y a-t-il une liste de directives ou quelque chose? Par exemple, dois-je utiliser des crochets ou des parenthèses? Comment utiliser l'espacement? Et si l'argument est une liste? Merci!

shell command-line command-line-arguments Yifan
la source
8
Je pense que GNU a quelques indices. Je regarderais ce que font la plupart des utilitaires GNU.
Basile Starynkevitch
1
@DanielPryden Je pense que la réponse à cette question est un peu trompeuse. Il donne des liens qui expliquent quels commutateurs doivent être acceptés et non à quoi --helpdevrait ressembler la sortie de . Mais les deux questions sont un bon candidat pour une fusion.
pmr
@pmr: Je suis d'accord - peut-être qu'un mod peut fusionner les questions pour nous.
Daniel Pryden
2
Je regarderais ce que font la plupart des utilitaires GNU et je le ferais dans l'autre sens.
Yakov Galka du

Réponses:

160

En règle générale, la sortie de votre aide doit inclure:

  • Description de ce que fait l'application
  • Syntaxe d'utilisation, qui:
    • Utilise [options]pour indiquer où vont les options
    • arg_name pour un argument singulier requis
    • [arg_name] pour un argument singulier facultatif
    • arg_name... pour un argument requis dont il peut y en avoir plusieurs (c'est rare)
    • [arg_name...] pour un argument pour lequel un nombre peut être fourni
    • notez que cela arg_namedevrait être un nom court descriptif, en bas, cas de serpent
  • Une liste d'options bien formatées, chacune:
    • avoir une courte description
    • montrant la valeur par défaut, s'il y en a une
    • montrant les valeurs possibles, le cas échéant
    • Notez que si une option peut accepter une forme courte (par exemple -l) ou une forme longue (par exemple --list), incluez-les ensemble sur la même ligne, car leurs descriptions seront les mêmes
  • Bref indicateur de l'emplacement des fichiers de configuration ou des variables d'environnement qui pourraient être la source d'arguments de ligne de commande, par exemple GREP_OPTS
  • S'il y a une page de manuel, indiquez-la en tant que telle, sinon, un bref indicateur où une aide plus détaillée peut être trouvée

Notez en outre qu'il est bon d'accepter les deux -het --helpde déclencher ce message et que vous devez afficher ce message si l'utilisateur gâche la syntaxe de la ligne de commande, par exemple omet un argument requis.

davetron5000
la source
3
Que faire si j'ai deux formes d'un seul argument requis? Par exemple , de façon plus classique de dire: à usage: move (+|-)pixelssavoir lorsque l' un + ou - est obligatoire ? (Je sais que je peux avoir 2 lignes d'utilisation mais j'aime l'idée de les doubler avec chaque nouvel argument.) Pouvez-vous penser à un exemple à partir d'un outil standard?
Alois Mahdal
4
@AloisMahdal Je vois habituellement {a|b|c|...}dans les sections d'aide pour SysV scripts de service INIT / arriviste, qui nécessitent un argument singulier qui est l' un a, b, c, etc. Par exemple, service sddmsans argument sur mon système imprime sur Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. Donc, la plupart des gens comprendraient probablement usage: move {+|-}pixels}, surtout si un exemple est donné:example: move +5
Braden Best
@JorgeBucaran, ils ne devraient pas sortir avec le statut 0, n'est-ce pas? Je crois que quitter avec le statut 2 est la norme pour les commandes shell invalides.
inavda
91

Jetez un oeil à docopt . Il s'agit d'une norme formelle de documentation (et d'analyse automatique) des arguments de ligne de commande.

Par exemple...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...
Lily Finley
la source
46

Je pense qu'il n'y a pas de syntaxe standard pour l'utilisation de la ligne de commande, mais la plupart utilisent cette convention:

Syntaxe de ligne de commande Microsoft , IBM a une syntaxe de ligne de commande similaire

  • Text without brackets or braces

    Éléments que vous devez saisir comme indiqué

  • <Text inside angle brackets>

    Espace réservé pour lequel vous devez fournir une valeur

  • [Text inside square brackets]

    Éléments facultatifs

  • {Text inside braces}

    Ensemble d'éléments requis; choisissez-en un

  • Barre verticale {a|b}

    Séparateur pour les articles mutuellement exclusifs; choisissez-en un

  • Ellipse <file> …

    Éléments pouvant être répétés

Aile d'acier
la source
16

Nous utilisons Linux, un système d'exploitation principalement compatible POSIX. Normes POSIX il devrait être: Syntaxe de l'argument utilitaire .

  • Une option de est un trait d' union suivi d'un seul caractère alphanumérique, comme ceci: -o.
  • Une option peut nécessiter un argument (qui doit apparaître immédiatement après l'option); par exemple, -o argumentou -oargument.
  • Les options qui ne nécessitent pas d'arguments peuvent être regroupées après un trait d'union, donc, par exemple, -lstest équivalent à -t -l -s.
  • Les options peuvent apparaître dans n'importe quel ordre; -lstest donc équivalent à -tls.
  • Les options peuvent apparaître plusieurs fois.
  • Les options précèdent les autres arguments de non- -lstoption : la non- option.
  • L' --argument met fin aux options.
  • L' -option est généralement utilisée pour représenter l'un des flux d'entrée standard.
MotherDawg
la source
2
Il est courant que l'utilisation sous GNU / Linux ne suive pas exactement cette norme. Exécuter par exemple , man aptitudequi sort ce (entre autres): aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Il contient {et} pour lier d'autres commandes obligatoires. Je pense (et) pourrait être utilisé pour la même chose comme ils sont utilisés dans docopt .
jarno
Cette réponse sera beaucoup moins utile si le lien fourni tombe en panne. Peut-être pourriez-vous résumer les parties importantes du document lié dans la réponse elle-même?
domsson
11

Microsoft a sa propre spécification Standard Command Line :

Ce document s'adresse aux développeurs d'utilitaires de ligne de commande. Collectivement, notre objectif est de présenter une expérience utilisateur de ligne de commande cohérente et composable. Atteindre qui permet à un utilisateur d'apprendre un ensemble de concepts de base (syntaxe, dénomination, comportements, etc.) et ensuite de pouvoir traduire ces connaissances en travaillant avec un large ensemble de commandes. Ces commandes devraient être capables de produire des flux de données normalisés dans un format normalisé pour permettre une composition facile sans avoir à analyser les flux de texte de sortie. Ce document est écrit pour être indépendant de toute implémentation spécifique d'un shell, d'un ensemble d'utilitaires ou de technologies de création de commandes; cependant, l'annexe J - Utilisation de Windows Powershell pour implémenter la norme de ligne de commande Microsoft montre comment l'utilisation de Windows PowerShell fournira gratuitement la mise en œuvre de bon nombre de ces directives.

Jared Harley
la source
9
Microsoft a une aide en ligne de commande terrible pour la plupart des utilitaires, tout est si horrible qu'ils ont fait Powershell pour cacher la ligne de commande "régulière" sous le tapis.
Camilo Martin
25
Je ne pense pas que la réponse doive être rétrogradée simplement parce qu'elle fait référence à la norme de Microsoft. "tout est si horrible" est une opinion subjective. De la même manière, on peut dire que la ligne de commande d'UNIX est horrible et laide, mais gardons ces opinions à l'écart et soyons professionnels.
Dima
2
D'accord, ce n'est pas la raison pour laquelle cette réponse devrait être rejetée. En cas de vote négatif, cela devrait être dû au fait que a) la section du document citée ne répond pas à la question posée, et b) le document lié ne semble pas pertinent. La question demande s'il existe des normes pour le «texte d'aide» avec un fort accent sur la syntaxe utilisée pour communiquer les synopsis d'utilisation des commandes. Le document n'a pas proférer une telle syntaxe , mais plutôt la façon de construire de bonnes applications en ligne de commande en général dans l'écosystème PowerShell (par exemple , doit prendre en charge -?, -Help, -Version, etc.). La réponse de l'OMI Steely Wing est plus proche de la réalité.
Mark G.
9

La norme de codage GNU est une bonne référence pour des choses comme celle-ci. Cette section traite de la sortie de --help. Dans ce cas, ce n'est pas très spécifique. Vous ne pouvez probablement pas vous tromper en imprimant un tableau montrant les options courtes et longues et une description succincte. Essayez d'obtenir l'espacement entre tous les arguments pour une meilleure lisibilité. Vous souhaiterez probablement fournir une manpage (et éventuellement un infomanuel) pour votre outil afin de fournir une explication plus élaborée.

pmr
la source
0

oui, vous êtes sur la bonne voie.

oui, les crochets sont l'indicateur habituel pour les éléments optionnels.

En règle générale, comme vous l'avez esquissé, il y a un résumé en ligne de commande en haut, suivi de détails, idéalement avec des échantillons pour chaque option. (Votre exemple montre des lignes entre chaque description d'option, mais je suppose qu'il s'agit d'un problème d'édition et que votre programme réel génère des listes d'options en retrait sans lignes vides entre les deux. Ce serait la norme à suivre dans tous les cas.)

Une tendance plus récente, (peut-être existe-t-il une spécification POSIX qui résout ce problème?), Est l'élimination du système de page de manuel pour la documentation et l'inclusion de toutes les informations qui figureraient dans une page de manuel dans le cadre de la program --helpsortie. Cet extra comprendra des descriptions plus longues, des concepts expliqués, des exemples d'utilisation, des limitations et des bogues connus, comment signaler un bogue, et éventuellement une section `` voir aussi '' pour les commandes associées.

J'espère que ça aide.

shellter
la source
4
Non non Non. La commande doit avoir une page de manuel qui comprend une référence d'utilisation détaillée complète, et -h|--helpdoit être juste une référence résumée. Vous pouvez également inclure une documentation plus complète (tutoriels, etc ...) dans des pages HTML ou info. Mais la page de manuel devrait être là!
ninjalj
Je suis d'accord avec vous, @ninjalj, mais comme je l'ai dit, "Une nouvelle tendance", et j'entends par là que les deux systèmes que j'utilise, UWin et MinGW, sont tous deux accompagnés d'une documentation intégrée. Je pense que la documentation intégrée a sa place, en particulier pour les petits scripts de niveau utilisateur, comme ce que propose cet utilisateur. Doit-il avoir à apprendre nroff et .info? Mais bon de nous garder honnêtes, merci pour vos commentaires et bonne chance à tous.
shellter
Personnellement, lorsque je tape someCommand --helpsur ma coque, tout ce dont j'ai besoin est un petit rappel de l'ordre précis dans lequel les arguments entrent, pas une bande géante de texte qui remplit l'écran, ce qui nécessite que je le canalise lessjuste pour tout voir. La page de manuel doit être l'endroit où vous mettez la longue description détaillée, pas le texte d'aide.
AJMansfield
selon le créateur de docopt dans sa conférence, il mentionne que POSIX a une norme pour cela.
v.oddou
0

Je suivrais des projets officiels comme tar comme exemple. À mon avis, aider msg. doit être aussi simple et descriptif que possible. Les exemples d'utilisation sont également bons. Il n'y a pas vraiment besoin d'une "aide standard".

rluks
la source
En ce qui concerne tar... si quelqu'un va faire un utilitaire divin comme tar, veuillez rendre les commutateurs courts mémorables et inclure une section "exemple d'utilisation" dans le --help. 90% du temps je regarde les instructions de tar pour extraire un simple tar.gz.
Camilo Martin
« Il n'y a pas vraiment besoin d'une" aide standard ". «Existe-t-il un« réel besoin »pour la plupart des choses que nous utilisons? Ou sont-ils simplement là pour nous faciliter la vie? Avoir une façon convenue de représenter les options est utile non seulement pour les lecteurs, mais aussi par exemple, il serait utile de créer des interfaces graphiques, par exemple, qui peuvent contrôler des utilitaires de ligne de commande arbitraires et veulent fournir des contrôles pour définir leurs options. Il y a probablement de meilleures utilisations que je n'ai pas encore envisagées.
underscore_d