如何编写使用说明

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拆分为组件可以降低用户必须查看的复杂性。