在手册页中记录可变长度选项的正确方法

在手册页中记录可变长度选项的正确方法

有时我会看到类似的使用信息

some_utility [arg [arg [...]]]

或者

some_utility [arg[, arg[...]]]

这表明您可以传递多个相同的参数。

我也看过类似的

some_utility [args]

或者

some_utility [arg][, arg][...]

有没有标准的方法来做到这一点?

答案1

不,不是真的,但大多数时候它是相当一致的。大多数手册会列出带方括号 ( ) 的可选参数[foo],带尖括号的强制参数或根本不带括号(<bar>, baz,后一个通常带有下划线)。

另外,在几乎所有情况下,如果参数的数量是可变的,您将拥有某种列表(如您所提到的,[quux ...][quux[, quux[...]]]......),其中类似地[quuz]大多数情况下都准确地表示争论。在极少数情况下,[quuz]也可能意味着“一个或多个参数”,但大多数手册都遵循列表形式的省略号。

这是一个准标准,但你不能绝对依赖它。但根据我的经验,95%的情况下都是没问题的。

重点是,有数百家各种颜色的软件供应商,不仅有“大玩家”,而且还有由个人编写的被证明有用的软件。他们所有人(希望)以某种个人的方式编写他们的联机帮助页……他们中的大多数人都知道足够长的时间来处理常见的约定,但也有一些人不关心或对风格品味等有某种精神缺陷; )

相关内容