J.5.时尚指南
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 命令。