参考页面应遵循标准布局。这使用户能够更快速地找到所需信息,并且还鼓励编写者记录命令的所有相关方面。一致性不仅在 PostgreSQL 参考页面中需要,在操作系统和其他软件包提供的参考页面中也需要。因此制定了以下指南。它们在很大程度上与各种操作系统制定的类似指南一致。
描述可执行命令的参考页面应按此顺序包含以下部分。不适用的部分可以省略。其他顶级部分仅应在特殊情况下使用;通常这些信息属于 “用法” 部分。
此部分会自动生成。它包含命令名称及其功能的半句摘要。
此部分包含命令的语法图。语法通常不应列出每个命令行选项;这将在下面完成。相反,列出命令行的主要组件,例如输入和输出文件的位置。
几段说明命令的作用。
描述每个命令行选项的列表。如果选项很多,可以使用子部分。
如果程序使用 0 表示成功,使用非零表示失败,则无需记录。如果不同的非零退出代码有不同的含义,请在此处列出它们。
描述程序的任何子语言或运行时接口。如果程序不是交互式的,则通常可以省略此部分。否则,此部分是描述运行时功能的万金油。如果合适,请使用子部分。
列出程序可能使用的所有环境变量。尽量完整;即使像 SHELL
这样的看似微不足道的变量也可能对用户感兴趣。
列出程序可能隐式访问的任何文件。也就是说,不要列出在命令行中指定的输入和输出文件,但要列出配置文件等。
解释程序可能创建的任何异常输出。不要列出每个可能的错误消息。这需要大量工作,在实践中几乎没有用处。但是,如果说,错误消息具有用户可以解析的标准格式,那么这里将是解释它的位置。
任何不适合其他地方的内容,但特别是错误、实现缺陷、安全考虑因素、兼容性问题。
示例
如果程序的历史中有一些重大里程碑,则可能会在此处列出。通常,可以省略此部分。
作者(仅在 contrib 部分中使用)
交叉引用,按以下顺序列出:其他 PostgreSQL 命令参考页、PostgreSQL SQL 命令参考页、PostgreSQL 手册的引用、其他参考页(例如,操作系统、其他软件包)、其他文档。同一组中的项目按字母顺序排列。
描述 SQL 命令的参考页应包含以下部分:名称、概要、描述、参数、输出、注释、示例、兼容性、历史、另请参阅。参数部分类似于选项部分,但对于可以列出哪些命令子句有更大的自由度。仅当命令返回除默认命令完成标记以外的内容时,才需要输出部分。兼容性部分应解释此命令在多大程度上符合 SQL 标准或与其他哪个数据库系统兼容。SQL 命令的另请参阅部分应在交叉引用程序之前列出 SQL 命令。