Shell 脚本 : conventions to write usage text for parameters?

Question

我对如何在脚本中编写参数和参数的用法文本感到困惑。无论我在哪里看，它总是不同的。尤其是参数的描述方式及其语法各不相同。

例如需要带文件名的标志的参数的用法

$0 -f <filename>
$0 [-f filename]
$0 [-f] <filename>
$0 [-f] [filename]
$0 [-f <filename>]
$0 [-f] [<filename>]

例如可选参数的用法(-f、-g、-h)

$0 [-fgh]
$0 [<optional>]
$0 [-[fgh]]
$0 [-<fgh>]
$0 -fgh
$0 -[fgh]

等等。

这可能是一个小问题，但很烦人，因为语法总是不同的，有时它实际上意味着不同的东西，但你看不到它，因为它不遵循任何约定。您对此有何看法，使用适当的语法编写用法文本的最佳实践是什么？

Answer 1

POSIX 定义了一个 convention for utility argument syntax (奇怪的是，他们似乎忘记在 ] 和后面的 [ 分组之间放置空格，就像他们在实际的实用程序描述页面上所做的那样(例如 command 和 find )):

“包含在‘[’和‘]’符号中的参数或选项参数是可选的，可以省略。”因此，“非封闭”(“封闭？”)参数是强制性的。

“通常，需要用实际值替换的参数名称用嵌入的下划线显示。或者，参数显示如下:

<parameter name>

"

“由‘|’竖线符号分隔的参数是互斥的。”

“省略号(“...”)用于表示允许选项或操作数出现一次或多次。”