2024年9月26日:PostgreSQL 17 发布!
支持的版本:当前 (17) / 16 / 15 / 14 / 13 / 12
开发版本:开发版
不支持的版本:11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4

J.6. 样式指南 #

J.6.1. 参考页 #

参考页应遵循标准布局。这允许用户更快地找到所需的信息,并且还鼓励编写者记录命令的所有相关方面。一致性不仅在PostgreSQL参考页之间是需要的,而且在操作系统和其他软件包提供的参考页中也是需要的。因此,制定了以下指南。它们在很大程度上与各种操作系统制定的类似指南一致。

描述可执行命令的参考页应按以下顺序包含以下部分。不适用的部分可以省略。额外的顶级部分仅应在特殊情况下使用;通常,这些信息属于用法部分。

名称 #

此部分由系统自动生成。它包含命令名称及其功能的半句摘要。

概要 #

此部分包含命令的语法图。概要通常不应列出每个命令行选项;这在下面完成。相反,列出命令行的主要组件,例如输入和输出文件的位置。

描述 #

几段解释命令的作用。

选项 #

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

退出状态 #

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

用法 #

描述程序的任何子语言或运行时接口。如果程序不是交互式的,则通常可以省略此部分。否则,此部分是用于描述运行时功能的总汇。在适当的情况下使用子部分。

环境 #

列出程序可能使用的所有环境变量。尽量完整;即使看似微不足道的变量,如SHELL,也可能对用户感兴趣。

文件 #

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

诊断 #

解释程序可能创建的任何异常输出。避免列出每种可能的错误消息。这需要大量工作,在实践中用处不大。但是,如果例如错误消息具有用户可以解析的标准格式,则应在此处进行解释。

注释 #

任何不适合放在其他地方的内容,尤其是错误、实现缺陷、安全注意事项、兼容性问题。

示例 #

示例

历史 #

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

作者 #

作者(仅在 contrib 部分使用)

参见 #

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

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

提交更正

如果您在文档中看到任何不正确的内容、与您对特定功能的体验不符的内容或需要进一步澄清的内容,请使用此表单报告文档问题。