web-dev-qa-db-fra.com

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

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

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 le texte d'aide de divers outils, mais existe-t-il une liste de directives ou quelque chose du genre? 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!

shellcommand-linecommand-line-arguments
202
Yifan

Généralement, votre aide devrait inclure:

  • Description de ce que l'application fait
  • Syntaxe d'utilisation, qui:
    • Utilise [options] pour indiquer où vont les options
    • arg_name pour un argument requis, singulier
    • [arg_name] pour un argument optionnel singulier
    • arg_name... pour un argument requis dont il peut y avoir beaucoup (c'est rare)
    • [arg_name...] pour un argument pour lequel n'importe quel nombre peut être fourni
    • notez que arg_name devrait être un nom court, descriptif, en bas, casse-tête
  • Une liste d'options bien formatée, chacune:
    • avoir une courte description
    • montrant la valeur par défaut, s'il en existe un
    • montrant les valeurs possibles, si cela s'applique
    • Notez que si une option peut accepter une forme abrégée (par exemple -l) ou une forme longue (par exemple --list), incluez-les ensemble sur la même ligne, car leurs descriptions seront identiques.
  • Brève indication de l’emplacement des fichiers de configuration ou des variables d’environnement pouvant être la source des arguments en ligne de commande, par exemple. GREP_OPTS
  • S'il y a une page de manuel, indiquez-le comme tel, sinon, un bref indicateur indiquant où une aide plus détaillée peut être trouvée

Notez en outre qu'il est judicieux d'accepter à la fois -h et --help pour déclencher ce message et que vous devez afficher ce message si l'utilisateur modifie la syntaxe de la ligne de commande, par exemple. omet un argument requis.

138
davetron5000

Jetez un oeil à docopt . C'est un standard formel pour documenter (et analyser automatiquement) les 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>...
72
Lily Finley

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:

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

  • Text without brackets or braces

    Articles que vous devez taper 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

  • Ellipsis <file> …

    Articles qui peuvent être répétés

32
Steely Wing

Nous utilisons Linux, un système d'exploitation principalement compatible POSIX. Les standards POSIX devraient être: syntaxe d'argument utilitaire .

13
MotherDawg

Microsoft a ses propres spécification standard de ligne de commande :

Ce document est destiné aux développeurs d’utilitaires de ligne de commande. Ensemble, notre objectif est de présenter une expérience utilisateur cohérente et composable en ligne de commande. Réaliser cela permet à un utilisateur d’apprendre un ensemble de concepts de base (syntaxe, dénomination, comportements, etc.), puis de traduire ces connaissances en travail avec un grand ensemble de commandes. Ces commandes doivent être en mesure de produire des flux de données normalisés dans un format normalisé afin de permettre une composition facile sans la charge d'analyse des flux de texte en sortie. Ce document est écrit de manière à ê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 permet d'implémenter gratuitement la plupart de ces instructions.

9
Jared Harley

La GNU Coding Standard 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 indiquant les options courtes et longues et une description succincte. Essayez d’obtenir l’espacement entre tous les arguments pour plus de lisibilité. Vous voudrez probablement fournir une page man (et éventuellement un manuel info) pour que votre outil fournisse une explication plus élaborée.

9
pmr

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

0
rluks

oui, vous êtes sur la bonne voie.

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

Comme vous l'avez esquissé, vous trouverez généralement 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 que c’est un problème d’édition et que votre programme réel génère des listes d’options en retrait sans lignes vierges. C’est la norme à suivre dans tous les cas.)

Une tendance récente, (il existe peut-être une spécification POSIX qui répond à cela?), Est la suppression du système de pages de manuel pour la documentation et l’inclusion de toutes les informations qui figureraient dans une page de manuel dans le cadre de la sortie program --help. Cet extra comprendra des descriptions plus longues, les concepts expliqués, des exemples d’utilisation, des limitations et des bugs connus, comment signaler un bogue et éventuellement une section "voir aussi" pour les commandes associées.

J'espère que ça aide.

0
shellter