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