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

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, est-ce que j’utilise des crochets ou des parenthèses? Comment utiliser l’espacement? Et si l’argument est une liste? Merci!

En règle générale, votre aide devrait 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 requirejs
    • [arg_name] pour un argument optionnel, singulier
    • arg_name… pour un argument requirejs dont il peut y en avoir beaucoup (c’est rare)
    • [arg_name…] pour un argument pour lequel un nombre quelconque peut être fourni
    • notez que arg_name devrait être un nom descriptif, un nom abrégé, en bas, un 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, si cela s’applique
    • 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 pouvant être la source des arguments de la ligne de commande, par exemple GREP_OPTS
  • S’il y a une page de manuel, indiquez en tant que telle, sinon un bref indicateur de l’endroit où une aide plus détaillée peut être trouvée.

Notez en outre que c’est une bonne forme d’accepter les deux -h et --help pour déclencher ce message et que vous devriez afficher ce message si l’utilisateur perturbe la syntaxe de la ligne de commande, par exemple en omettant un argument requirejs.

Jetez un oeil à docopt . C’est une norme formelle pour la documentation (et l’parsing automatique) des arguments de ligne de commande.

Par exemple…

 Usage: my_program command --option  my_program [] my_program --another-option= my_program (--either-that-option | ) my_program  ... 

Nous exécutons Linux, un système d’exploitation principalement compatible POSIX. Les normes POSIX devraient être: Syntaxe de l’argument utilitaire .

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 voulez probablement fournir une page de manuel (et éventuellement un manuel d’ info ) pour que votre outil fournisse une explication plus élaborée.

Microsoft a une syntaxe de ligne de commande

  • Texte sans parenthèses ni accolades

    Articles que vous devez taper comme indiqué

  • Placeholder pour lequel vous devez fournir une valeur

  • [Texte entre crochets]

    Éléments facultatifs

  • {Texte entre accolades}

    Ensemble d’éléments requirejs; choisissez-en un

  • Barre verticale (|)

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

  • Ellipse (…)

    Articles pouvant être répétés

Microsoft a sa propre spécification de ligne de commande standard :

Ce document concerne les développeurs d’utilitaires de ligne de commande. Collectivement, notre objective est de présenter une expérience utilisateur cohérente et composable en ligne de commande. Cela permet à un utilisateur d’apprendre un ensemble de concepts de base (syntaxe, dénomination, comportements, etc.), puis de traduire ces connaissances en un ensemble de commandes important. Ces commandes devraient être capables de générer des stream de données standardisés dans un format standardisé pour permettre une composition facile sans avoir à parsingr des stream 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 l’implémentation de plusieurs de ces directives.

oui, vous êtes sur la bonne voie.

oui, les crochets sont l’indicateur habituel pour les éléments facultatifs.

Généralement, comme vous l’avez esquissé, il existe un résumé en ligne de commande, suivi des détails, idéalement avec des exemples pour chaque option. (Votre exemple montre des lignes entre chaque description d’option, mais je suppose que c’est un problème d’édition, et que votre vrai programme affiche des listes d’options en retrait sans lignes blanches. Ce serait la norme à suivre.)

Une nouvelle tendance, (il y a peut-être une spécification POSIX qui résout ce problème?), Est l’élimination du système de page de manuel pour la documentation et toutes les informations qui figureraient dans une page de program --help . Cet extra inclura des descriptions plus longues, des concepts expliqués, des exemples d’utilisation, des limitations connues et des bogues, comment signaler un bogue, et éventuellement une section «voir aussi» pour les commandes associées.

J’espère que ça aide.

Je suivrais des projets officiels comme le goudron comme exemple. A mon avis, aide msg. doit être simple et descriptif que possible. Les exemples d’utilisation sont bons aussi. Il n’y a pas vraiment besoin d’aide standard.