Existe-t-il un format "standard" pour le texte d'aide de la ligne de commande/du shell ?

Question

Si ce n'est pas le cas, existe-t-il une norme de facto ? En gros, 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

J'ai fait cela en lisant simplement le texte d'aide de divers outils, mais existe-t-il une liste de directives ou quelque chose du genre ? Par exemple, dois-je utiliser des crochets ou des parenthèses ? Comment utiliser l'espacement ? Que faire si l'argument est une liste ? Merci !

Answer 1

Typiquement, votre sortie d'aide devrait inclure :

• Description de ce que fait l'application
• Syntaxe d'utilisation, qui :
  • Utilisations [options] pour indiquer où vont les options
  • arg_name pour un arg nécessaire et singulier
  • [arg_name] pour un arg facultatif et singulier
  • arg_name... pour un arg requis qui peut être très nombreux (ce qui est rare)
  • [arg_name...] pour un arg pour lequel un nombre quelconque peut être fourni
  • notez que arg_name doit être un nom court et descriptif, en minuscules et en majuscules.
• Une liste d'options joliment formatée, chacune :
  • avoir une courte description
  • afficher la valeur par défaut, s'il y en a une
  • montrant les valeurs possibles, si cela s'applique
  • Notez que si une option peut accepter une forme courte (par ex. -l ) ou une forme longue (par ex. --list ), incluez-les ensemble sur la même ligne, car leurs descriptions seront les mêmes.
• Brève indication de l'emplacement des fichiers de configuration ou des variables d'environnement qui pourraient être la source d'arguments de ligne de commande, par ex. GREP_OPTS
• S'il existe une page de manuel, indiquez-la comme telle ; sinon, indiquez brièvement où vous pouvez trouver une aide plus détaillée.

Notez en outre qu'il est de bon ton d'accepter à la fois -h y --help pour déclencher ce message et que vous devez afficher ce message si l'utilisateur se trompe dans la syntaxe de la ligne de commande, par exemple s'il omet un argument obligatoire.

Answer 2

Jetez un coup d'œil à docopt . Il s'agit d'un standard formel pour documenter (et analyser automatiquement) les arguments de la 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>...

Answer 3

Le GNU Coding Standard est une bonne référence pour ce genre de choses. Cette section traite de la sortie de --help . Dans ce cas, il n'est pas très spécifique. Vous ne pouvez probablement pas vous tromper en imprimant un tableau indiquant les options courtes et longues et une description succincte. Essayez d'obtenir un espacement correct entre tous les arguments pour une meilleure lisibilité. Vous voudrez probablement fournir un man (et éventuellement une page info manuel) de votre outil pour fournir une explication plus élaborée.

Answer 4

Oui, vous êtes sur la bonne voie.

oui, les crochets sont l'indicateur habituel des éléments facultatifs.

En général, comme vous l'avez esquissé, il y a un résumé de la ligne de commande en haut, suivi de détails, idéalement avec des exemples 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 produit des listes d'options indentées sans lignes vides entre elles. Ce serait la norme à suivre dans tous les cas).

Une tendance plus récente (il existe peut-être une spécification POSIX qui traite de ce sujet) est l'élimination du système de pages de manuel pour la documentation, et l'inclusion de toutes les informations qui seraient dans une page de manuel comme faisant partie de la page de manuel de l'utilisateur. program --help sortie. Ce supplément comprendra des descriptions plus longues, des concepts expliqués, des exemples d'utilisation, des limitations et des bogues connus, la façon de signaler un bogue, et éventuellement une section "voir aussi" pour les commandes connexes.

J'espère que cela vous aidera.

Answer 5

Je suivrais l'exemple de projets officiels comme tar. À mon avis, les messages d'aide doivent être aussi simples et descriptifs que possible. Des exemples d'utilisation sont également utiles. Il n'y a pas vraiment besoin d'une "aide standard".