如何编写使用说明

Question

我的脚本可以这样调用：

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使用说明？

Answer 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拆分成组件，降低了用户必须查看的内容的复杂性。