命令行/ shell帮助文本是否有“标准”格式？

如果没有，是否存在事实上的标准？基本上，我在编写命令行帮助文本，如下所示：

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

我基本上是从阅读各种工具的帮助文本中得出的，但是有一些指导方针或其他内容吗？例如，我使用方括号还是括号？如何使用间距？如果参数是列表怎么办？谢谢！

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

• 应用功能说明
• 使用语法，其中：
  • 用于[options]指示选项的位置
  • arg_name 对于必需的单数arg
  • [arg_name] 用于可选的单数arg
  • arg_name... 对于所需的arg可以有很多（很少见）
  • [arg_name...] 对于可以提供任何数字的arg
  • 请注意，该名称arg_name应为描述性的简短名称（在小写蛇形情况下）
• 格式正确的选项列表，每个选项：
  • 简短说明
  • 显示默认值（如果有）
  • 显示可能的值（如果适用）
  • 请注意，如果一个选项可以接受短格式（例如-l）或长格式（例如--list），请将它们一起包含在同一行中，因为它们的描述将相同
• 配置文件或环境变量的位置的简要指示，它们可能是命令行参数的来源，例如 GREP_OPTS
• 如果有手册页，请进行指示，否则，简要指示可以在何处找到更详细的帮助

此外，值得注意的，它的好形式，同时接受-h并--help触发此消息，并认为你应该显示此消息，如果用户弄乱的命令行语法，例如省略了必要的参数。

看看docopt。它是记录（和自动解析）命令行参数的正式标准。

例如...

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>...

我认为命令行用法没有标准语法，但是大多数使用以下约定：

Microsoft 命令行语法，IBM具有类似的命令行语法

• Text without brackets or braces

  您必须输入的内容如下所示
  
  

• <Text inside angle brackets>

  您必须为其提供值的占位符
  
  

• [Text inside square brackets]

  可选项目
  
  

• {Text inside braces}

  一套必需的物品；选一个
  
  

• 竖条 {a|b}

  互斥项的分隔符；选一个
  
  

• 省略 <file> …

  可重复的项目
  
  

我们正在运行Linux，这是一个大多数与POSIX兼容的操作系统。它应该是POSIX标准：实用程序参数语法。

• 一个选项是一个连字符后跟单个字母数字字符，像这样：-o。
• 一个选项可能需要一个参数（必须在该选项之后立即出现）；例如-o argument或 -oargument。
• 不需要参数的选项可以在连字符后分组，例如，-lst等效于-t -l -s。
• 选项可以按任何顺序出现；因此-lst等于-tls。
• 选项可以出现多次。
• 选项在其他非选项参数之前：-lst非选项。
• 该--参数终止选项。
• 该-选项通常用于表示标准输入流之一。

Microsoft有自己的命令行标准规范：

本文档主要针对命令行实用程序的开发人员。总体而言，我们的目标是提供一致，可组合的命令行用户体验。实现使用户能够学习一组核心概念（语法，命名，行为等），然后能够将该知识转化为使用大量命令的工具。这些命令应该能够以标准化格式输出标准化的数据流，以便在不解析输出文本流的负担的情况下轻松进行编写。本文档的编写独立于Shell，实用程序集或命令创建技术的任何特定实现；但是，附录J-使用Windows Powershell实施Microsoft命令行标准显示了如何使用Windows PowerShell免费提供许多这些准则的实施。

对于这样的事情，GNU编码标准是一个很好的参考。本节处理的输出--help。在这种情况下，它不是很具体。打印一张显示简短和长期选项以及简洁描述的表格，可能不会出错。尝试正确获取所有参数之间的间距以提高可读性。您可能希望为您的工具提供一个man页面（可能还有info手册），以提供更详细的说明。

是的，您的方向正确。

是的，方括号是可选项目的常用指示。

通常，正如您所勾勒的那样，顶部是命令行摘要，其后是详细信息，最好是每个选项都带有示例。（您的示例显示了每个选项描述之间的行，但我认为这是一个编辑问题，您的真实程序输出的是缩进的选项列表，中间没有空格。在任何情况下，这都是要遵循的标准。）

一种新的趋势（也许有POSIX规范可以解决这个问题？）是取消了手册页系统的文档，并将手册页中的所有信息作为program --help输出的一部分包括在内。额外的内容将包括更长的描述，解释的概念，用法示例，已知的限制和错误，如何报告错误，以及可能的相关命令“另请参见”部分。

我希望这有帮助。

我将以tar等官方项目为例。我认为帮助味精。需要尽可能简单和描述性。使用示例也很好。真正不需要“标准帮助”。