我正在尝试编写一些规范以在一个小团队之间共享,并且对我放置一些命令列表的格式很挑剔。手册页的 SYNOPSIS 部分中使用的语法是否有任何正式定义?
来自 Wikimedia Commons,这里有一个手册页示例,其中包含我正在谈论的 SYNOPSIS 部分,其中列出了命令及其理解的必需和可选参数。
任何地方都没有正式的联机帮助页定义,即使在 POSIX 标准中也是如此。您示例中的man(1)
联机帮助页非常典型:您写出了程序可以使用的各种方式(通常只有一种),[]
表示可选,粗体(或带有mdoc
宏的打字机字体)表示文字命令行输入,斜体表示变量。
手册页将解释最重要的约定man(7)
。用于旧式 Unix 联机帮助页,在 Linux 上仍然很流行(请参阅 参考资料);来自 4.4BSD 并在其衍生产品中很受欢迎。后者保持更严格的内容和表示分离,并且可以生成(恕我直言)更漂亮的 PDF/HTML 输出mdoc(7)
man(7)
man-pages(7)
mdoc(7)
man 7 手册页:
简要描述命令或函数的接口。对于命令,这显示了命令的语法及其参数(包括选项);粗体字用于原样文本,斜体字用于表示可替换的参数。方括号 ([]) 包围可选参数,竖线 (|) 分隔选项,省略号 (...) 可以重复。对于函数,它显示任何必需的数据声明或#include 指令,然后是函数声明。
实用程序的实用程序约定记录在第 12 章。IEEE Std 1003.1, 2004 版的实用程序约定。
此文档的较新版本存在于此处