参考页应该遵循一种标准布局。这允许用户更快找到想要的信息,并且它也鼓励作者记录一个命令的所有相关方面。不止在PostgreSQL参考页中需要一致性,操作系统或其他包提供的参考页也需要。因此人们开发了下列方针。它们的大部分与由多个操作系统建立的类似方针保持一致。
描述可执行命令的参考页面应包含以下部分,并按此顺序排列。不适用的部分 可以省略。额外的顶级部分应仅在特殊情况下使用;通常这些信息应属于 “用法”部分。
本节是自动生成的。它包含命令名称及其功能的半句摘要。
本节包含该命令的语法图。概要通常不应列出每个命令行选项; 这些选项将在下面列出。相反,应列出命令行的主要组成部分, 例如输入和输出文件的位置。
几段解释该命令作用的文字。
描述每个命令行选项的列表。如果选项很多,可以使用小节。
如果程序使用0表示成功,非零表示失败, 那么您不需要对其进行文档记录。如果不同的非零退出代码有特定含义, 请在此列出它们。
描述程序的任何子语言或运行时接口。如果程序不是交互式的, 通常可以省略此部分。否则,此部分是用于描述运行时功能的 综合部分。如果合适,请使用子章节。
列出程序可能使用的所有环境变量。
尽量完整;即使是像SHELL
这样看似微不足道的变量,
也可能对用户有用。
列出程序可能隐式访问的任何文件。也就是说,不要列出在命令行上 指定的输入和输出文件,但要列出配置文件等。
解释程序可能产生的任何异常输出。避免列出每一个可能的错误消息。 这需要大量工作且在实际中用处不大。但是,如果例如错误消息具有用户 可以解析的标准格式,那么这里将是解释它的地方。
任何不适合其他地方的内容,特别是错误、实现缺陷、安全性考虑、 兼容性问题。
示例
如果程序历史中有一些重要的里程碑,它们可能会在这里列出。通常,这一部分可以省略。
作者(仅用于贡献部分)
交叉引用,按以下顺序列出:其他 PostgreSQL命令参考页面, PostgreSQL SQL命令参考页面, 引用PostgreSQL手册, 其他参考页面(例如,操作系统,其他软件包), 其他文档。同一组中的项目按字母顺序排列。
描述 SQL 命令的参考页应该包含下列小节:名称、概要、描述、参数、输出、注意、例子、兼容性、历史、另见。 用法、诊断、注意、例子、兼容性、历史、又见。参数小节类似选项小节, 但是在选择哪些子句是可列出的方面有更多自由。输出小节只有在命令返回非命令结束标签的东西时才需要。兼容性小节应该解释此命令遵循 SQL 标准的程度,或者它兼容哪种其它数据库系统。SQL 命令的另见小节应该在交叉引用其它程序之前列出 SQL 命令。