☰

命令概要的编写有标准吗？

tag-icon • tag-icon command-line man
命令概要的编写有标准吗？

在我看来，每个人对于如何写一篇文章都有自己的想法。概要描述命令用法对于最终用户。

例如，这是以下格式man grep：

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

现在它有一些出现在其他联机帮助页中的语法。 []被认为是可选的，并且...作为相同输入的多个才有意义。

但人们使用|or/代替 OR，还有其他人会颠倒[]含义。或者他们没有给出任何关于去向的指示[OPTIONS]。

我想遵循我所写内容的标准，但我查看的每个网站都告诉我一些不同的东西。

有没有实际的标准编写概要的方式，还是惯例只是人们长期以来一直在做的事情？

答案1

经典的标准来自 POSIX，实用程序参数语法（感谢@illuminÉ 提供更新的链接）。它描述了手册页中使用的语法，例如

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

作为经典，它建议使用单字符选项，并-W建议供应商使用，这就是多字符选项的适应方式（例如，请参阅gcc 选项总结）。

GNU 软件引入了以--. GNU 使用这些选项格式化手册页的一些指南可以在help2man 参考。

答案2

实际上，可以在;中寻找SYNOPSIS（惊喜！）找到一个答案。man 7 man-pages它说：

       SYNOPSIS      A brief summary of the command or function's interface.

                     For commands, this shows the syntax of  the  command  and
                     its  arguments  (including options); boldface is used for
                     as-is text and italics are used to  indicate  replaceable
                     arguments.   Brackets  ([])  surround optional arguments,
                     vertical bars (|) separate choices,  and  ellipses  (...)
                     can  be  repeated.   For functions, it shows any required
                     data declarations or #include directives, followed by the
                     function declaration.

                     Where  a  feature  test macro must be defined in order to
                     obtain the declaration of a function (or a variable) from
                     a header file, then the SYNOPSIS should indicate this, as
                     described in feature_test_macros(7).

相关内容