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

Question

如果没有，是否有事实上的标准？基本上我正在编写这样的命令行帮助文本：

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

我基本上只是通过阅读各种工具的帮助文本来做到这一点的，但是有指南列表之类的吗？例如，我使用方括号还是圆括号？如何使用间距？如果参数是一个列表怎么办？谢谢！

Answer 1

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

Answer 2

是的，你在正确的轨道上。

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

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

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

我希望这会有所帮助。

Answer 3

我会以 tar 等官方项目为例。在我看来帮助味精。需要尽可能简单和具有描述性。使用的例子也很好。没有真正需要“标准帮助”。

Answer 4

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

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

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

Answer 5

微软有自己的Command Line Standard specification：

本文档主要面向命令行实用程序的开发人员。总的来说，我们的目标是提供一致的、可组合的命令行用户体验。实现这一点允许用户学习一组核心概念（语法、命名、行为等），然后能够将这些知识转化为使用大量命令。这些命令应该能够以标准化格式输出标准化的数据流，以便轻松组合，而无需解析输出文本流。本文档的编写独立于 shell、实用程序集或命令创建技术的任何特定实现；但是，附录 J - 使用 Windows Powershell 实施 Microsoft 命令行标准展示了如何使用 Windows PowerShell 免费提供其中许多指南的实施。

Answer 6

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

Answer 7

我们正在运行 Linux，这是一个主要兼容 POSIX 的操作系统。 POSIX 标准应该是：Utility Argument Syntax。

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

Answer 8

我认为命令行使用没有标准语法，但大多数都使用这种约定：

微软Command-Line Syntax，IBM也有类似的Command-Line Syntax

---

• Text without brackets or braces

  您必须输入的项目如图所示
  
  

• <Text inside angle brackets>

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

• [Text inside square brackets]

  可选项目
  
  

• {Text inside braces}

  所需物品的集合；选一个
  
  

• 竖条{a|b}

  互斥项目的分隔符；选一个
  
  

• 省略号<file> …

  可以重复的项目
  
  

Answer 9

这可能是一个位题外话，但我曾经写过两个小工具，可以让命令行工具的创建和维护帮助页面更高效：

• MAIN DOCLET 通过处理源代码中的 Javadoc cmets 为 Java 程序的 main 方法生成 HTML 文档
• HTML2TXT tool 将 HTML 文档格式化为纯文本（这是我们想要的帮助文本）

我将这两个工具集成到我的程序的 MAVEN 构建过程中，以便它们在每次构建时自动执行。

例如：

• 我的 ZZFIND 工具的relevant source file
• 构建项目的POM file（并运行上述两个工具）
• Example output 当 ZZFIND 使用 --help 命令行选项运行时

希望这对其他人有用！？