如何编写使用说明答案

【问题标题】：How to write the usage notes如何编写使用说明
【发布时间】：2016-07-18 10:24:32
【问题描述】：

我的脚本可以这样调用：

myScript -a some_name
myScript -a all
myScript -b some_name
myScript -b all
myScript -c

如何编写它的使用说明？我知道[] 表示可选参数，| 表示替代，但在我的情况下，我需要 嵌套替代，类似于：

usage myScript (-a some_name | all) | (-b some_name | all) | -c

现在我认为我不能为此目的使用()，那么我还能怎么写呢？我必须改为多行还是有更好的方法？

myScript -a some_name | all
myScript -b some_name | all
myScript -c

我的意思是这在我的情况下仍然可以，但如果我有更多嵌套的替代方案，它会变得非常冗长。

还有没有详尽的资源描述标准的 unix/linux 使用说明？

【问题讨论】：

Is there a specification for a man page's SYNOPSIS section?的可能重复
这不是同一个问题。当然，man 页面的 SYNOPSIS 部分的语法相似/相同，但整体布局不同。我不想创建man 页面，只是在用户提供不正确参数时进行简单（和简短）的使用说明。老实说，我也想了解使用说明中是否有任何标准布局/缩进。
我没有暗示这是 same 问题，因此 possible 重复。它不是关于一般的手册页，而是关于可选、强制等参数的（建议的）语法/符号。当然是 YMMV。

【解决方案1】：

Docopt 提供了一个很好的资源来弄清楚这些事情应该如何进行，因为它是一个基于使用文档的参数解析器。

如果你想在一行中得到它，你可以这样做：

myScript ((-a|-b) (some_name|all) | -c)

但这相当混乱。我宁愿分两次做：

myScript (-a|-b) (some_name|all)
myScript -c

或者实际上是三个，因为您应该在其中添加 myScript --help。

如果我发现自己难以解释程序的 cli，我会停下来思考我是否设计得很好。 -a、-b 和-c 真的是命令，只能选择其中一个吗？然后将程序构造为具有子命令（例如 git）会更有意义：

myScript <command> [<args>]

Commands:
    a    Attach an aardvark.
    b    Belay the border.
    c    Capture the castle.

子命令有自己的帮助输出：

[$]> myScript a --help
Usage:
    myScript a <target>
    myScript a --help

仅对可选值使用选项有助于减少混淆（“我可以运行 myScript -a some_name -b all 吗？”），将 API 拆分为组件可以降低用户查看内容的复杂性。

【讨论】：

所以它的要点是——是的，我可以用括号来分组，对吗？
你可以做任何你想做的事。但是，使用文档的目的是让用户清楚地了解如何使用您的程序。无论您写的内容是否符合任何特定标准，都没有关系。人们是否理解它很重要。在编写软件时牢记这一目标，并在测试软件并了解人们如何使用它时牢记这一目标。
当然，您所写的是真实的，但如果有一个约定俗成的约定，而我试图写出违反它的使用说明，那么这可能会引起混淆。这是我想避免的情况。
是的，使用括号对项目进行分组是一种相当普遍的约定。当您开始考虑嵌套括号时，它变得不那么常见了，尽管我想大多数人都可以推断来理解它。