J.5.时尚指南

• J.5.1. 参考页

J.5.1. 参考页

参考页应遵循标准布局。这使用户可以更快地找到所需的信息，并且还鼓励编写者记录命令的所有相关方面。不仅在 PostgreSQL 参考页之间需要一致性，而且在 os 和其他软件包提供的参考页之间也要求一致性。因此，已经制定了以下准则。它们在大多数情况下与各种 os 构建的类似准则一致。

描述可执行命令的参考页应按 Sequences 包含以下部分。不适用的部分可以省略。其他顶级部分仅应在特殊情况下使用；该信息通常属于“用途”部分。

• Name

  • 此部分是自动生成的。它包含命令名称和其功能的半句摘要。

• Synopsis

  • 本节包含命令的语法图。概要通常不应列出每个命令行选项。在下面完成。而是列出命令行的主要组成部分，例如 Importing 和输出文件的位置。

• Description

  • 有几段说明了命令的作用。

• Options

  • 描述每个命令行选项的列表。如果有很多选项，则可以使用小节。

• Exit Status

  • 如果程序使用 0 表示成功，使用非零表示失败，则无需记录它。如果不同的非零退出代码后面有含义，请在此处列出。

• Usage

  • 描述程序的任何子语言或运行时界面。如果程序不是交互式的，则通常可以省略此部分。否则，本节将全面介绍运行时功能。如果合适，请使用小节。

• Environment

  • 列出程序可能使用的所有环境变量。尽量做到完整；用户可能甚至不喜欢看似微不足道的变量，例如SHELL。

• Files

  • 列出程序可能隐式访问的所有文件。也就是说，不要列出在命令行上指定的 Importing 和输出文件，而是列出配置文件等。

• Diagnostics

  • 解释程序可能创建的任何异常输出。不要列出所有可能的错误消息。这是很多工作，在实践中很少使用。但是，例如，如果错误消息具有用户可以解析的标准格式，则可以在此处进行解释。

• Notes

  • 任何不适合其他地方的东西，特别是错误，实现缺陷，安全性考虑事项，兼容性问题。

• Examples

  • Examples

• History

  • 如果程序历史上有一些重要的里程碑，则可以在此处列出。通常，此部分可以省略。

• Author

  • 作者(仅在 contrib 部分中使用)

• See Also

  • 交叉引用，按以下 Sequences 列出：其他 PostgreSQL 命令参考页面，PostgreSQL SQL 命令参考页面，对 PostgreSQL 手册的引用，其他参考页面(例如，os，其他软件包)，其他文档。同一组中的项目按字母 Sequences 列出。

描述 SQL 命令的参考页应包含以下部分：名称，概要，说明，参数，输出，Comments，示例，兼容性，历史记录，另请参见。 “参数”部分与“选项”部分相似，但是可以列出命令的哪些子句具有更大的自由度。仅当命令返回默认命令完成标记以外的内容时，才需要“输出”部分。兼容性部分应说明此命令在何种程度上符合 SQL 标准，或与哪个其他数据库系统兼容。 SQL 命令的“另请参见”部分应在交叉引用程序之前列出 SQL 命令。