PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

J.6. 风格指南 #

J.6.1. 参考手册页

J.6.1. 参考手册页 #

参考手册页应遵循标准的布局。这让用户能更快地找到所需信息,也促使 作者记录一个命令的所有相关方面。一致性不仅要在 PostgreSQL 各参考手册页之间保持,也要与 操作系统和其他软件包提供的参考手册页保持一致。因此我们制定了以下 准则。它们在很大程度上与各种操作系统建立的类似准则一致。

描述可执行命令的参考手册页应按此顺序包含以下小节。不适用的小节可以 省略。额外的顶层小节应只在特殊情况下使用;相关信息通常应归入 “Usage” 小节。

Name(名称) #

该小节自动生成。它包含命令名及其功能的半句话概括。

Synopsis(概要) #

该小节包含命令的语法图。概要通常不应逐个列出每个命令行选项; 那是在下面做的。它应列出命令行的主要组成部分,例如输入和输出 文件的位置。

Description(描述) #

用若干段落解释该命令做什么。

Options(选项) #

描述每个命令行选项的列表。如果选项很多,可以使用子小节。

Exit Status(退出状态) #

如果程序以 0 表示成功、非零表示失败,则无需记录。如果不同的 非零退出代码各有含义,请在此列出。

Usage(用法) #

描述程序的任何子语言或运行时接口。如果程序不是交互式的,这个 小节通常可以省略。否则,这个小节是描述运行时特性的兜底之处。 适当时可以使用子小节。

Environment(环境) #

列出程序可能使用的所有环境变量。尽量完整;即使是 SHELL 这样看似微不足道的变量也可能引起用户的 兴趣。

Files(文件) #

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

Diagnostics(诊断) #

解释程序可能产生的任何不寻常的输出。避免罗列所有可能的错误 消息;那是大量工作,而且实践中用处不大。但如果错误消息具有 用户可以解析的标准格式,这里就是解释它的地方。

Notes(注意) #

放不进其他小节的内容,特别是缺陷、实现瑕疵、安全考量、兼容性 问题。

Examples(示例) #

示例

History(历史) #

如果程序的历史上有一些重大里程碑,可以在这里列出。通常这个 小节可以省略。

Author(作者) #

作者(只在 contrib 部分使用)

See Also(参见) #

交叉引用,按以下顺序列出:其他 PostgreSQL 命令参考手册页、 PostgreSQL SQL 命令参考手册页、 PostgreSQL 手册的引用、其他参考手册页 (例如操作系统的、其他软件包的)、其他文档。同一组内的条目按 字母顺序排列。

描述 SQL 命令的参考手册页应包含以下小节:Name、Synopsis、 Description、Parameters、Outputs、Notes、Examples、Compatibility、 History、See Also。Parameters 小节类似于 Options 小节,但在列出命令 的哪些子句上有更大的自由度。只有当命令返回的内容不是默认的命令完成 标签时才需要 Outputs 小节。Compatibility 小节应说明该命令在多大程度 上符合 SQL 标准,或它与哪种其他数据库系统兼容。SQL 命令的 See Also 小节应把 SQL 命令列在指向程序的交叉引用之前。