有没有“标准"?命令行/shell 帮助文本的格式? [英] Is there a "standard" format for command line/shell help text?

问题描述

如果没有，是否有事实上的标准?基本上我正在写一个命令行帮助文本，如下所示:

If not, is there a de facto standard? Basically I'm writing a command line help text like so:

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

我基本上只是通过阅读各种工具的帮助文本来实现的，但是否有指南列表或其他内容?例如，我使用方括号还是圆括号?如何使用间距?如果参数是一个列表怎么办?谢谢！

I made that from basically just reading the help text of various tools, but is there a list of guidelines or something? For example, do I use square brackets or parentheses? How to use spacing? What if the argument is a list? Thanks!

推荐答案

通常，您的帮助输出应包括:

Typically, your help output should include:

• 对应用功能的描述
• 使用语法，其中:
  • 使用 [options] 来指示选项的去向
  • arg_name 用于必需的单数 arg
  • [arg_name] 用于可选的单数 arg
  • arg_name... 用于可能有很多(这种情况很少见)的必需 arg
  • [arg_name...] 用于可以提供任何数字的 arg
  • 请注意，arg_name 应该是一个描述性的短名称，以小写的蛇形大小写
  • Description of what the app does
  • Usage syntax, which:
    • Uses [options] to indicate where the options go
    • arg_name for a required, singular arg
    • [arg_name] for an optional, singular arg
    • arg_name... for a required arg of which there can be many (this is rare)
    • [arg_name...] for an arg for which any number can be supplied
    • note that arg_name should be a descriptive, short name, in lower, snake case
    • 有一个简短的描述
    • 显示默认值，如果有的话
    • 显示可能的值(如果适用)
    • 请注意，如果选项可以接受短格式(例如 -l)或长格式(例如 --list)，请将它们一起包含在同一行中，因为它们的描述是相同的
    • having a short description
    • showing the default value, if there is one
    • showing the possible values, if that applies
    • Note that if an option can accept a short form (e.g. -l) or a long form (e.g. --list), include them together on the same line, as their descriptions will be the same

    请进一步注意，接受 -h 和 --help 来触发此消息是一种很好的形式并且您应该显示此消息如果用户弄乱了命令行语法，例如省略必需的参数.

    Note further that it's good form to accept both -h and --help to trigger this message and that you should show this message if the user messes up the command-line syntax, e.g. omits a required argument.

    这篇关于有没有“标准"?命令行/shell 帮助文本的格式?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！