9.3 9.4 9.5 9.6 10 11 12 13 14 15 Current(16) 17
问题报告 纠错本页面

J.6. 样式指导 #

J.6.1. 参考页

J.6.1. 参考页 #

参考页应该遵循一种标准布局。这允许用户更快找到想要的信息,并且它也鼓励作者记录一个命令的所有相关方面。不止在PostgreSQL参考页中需要一致性,操作系统或其他包提供的参考页也需要。因此人们开发了下列方针。它们的大部分与由多个操作系统建立的类似方针保持一致。

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

名称 #

本节是自动生成的。它包含命令名称及其功能的半句摘要。

概要 #

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

描述 #

几段解释该命令作用的文字。

选项 #

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

退出状态 #

如果程序使用0表示成功,非零表示失败, 那么您不需要对其进行文档记录。如果不同的非零退出代码有特定含义, 请在此列出它们。

用法 #

描述程序的任何子语言或运行时接口。如果程序不是交互式的, 通常可以省略此部分。否则,此部分是用于描述运行时功能的 综合部分。如果合适,请使用子章节。

环境 #

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

文件 #

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

诊断 #

解释程序可能产生的任何异常输出。避免列出每一个可能的错误消息。 这需要大量工作且在实际中用处不大。但是,如果例如错误消息具有用户 可以解析的标准格式,那么这里将是解释它的地方。

注释 #

任何不适合其他地方的内容,特别是错误、实现缺陷、安全性考虑、 兼容性问题。

示例 #

示例

历史 #

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

作者 #

作者(仅用于贡献部分)

另请参阅 #

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

描述 SQL 命令的参考页应该包含下列小节:名称、概要、描述、参数、输出、注意、例子、兼容性、历史、另见。 用法、诊断、注意、例子、兼容性、历史、又见。参数小节类似选项小节, 但是在选择哪些子句是可列出的方面有更多自由。输出小节只有在命令返回非命令结束标签的东西时才需要。兼容性小节应该解释此命令遵循 SQL 标准的程度,或者它兼容哪种其它数据库系统。SQL 命令的另见小节应该在交叉引用其它程序之前列出 SQL 命令。