J.5. 样式指导

J.5.1. 参考页

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

描述可执行命令的参考页应该包含以下的小节,并且是按照介绍的顺序。不适用的小节可以被忽略。额外的顶层小节应该只被用在特殊的环境下;通常那些信息属于"Usage"小节。

名称

这个小节是自动生成的。它包含命令名称和对其功能的一个半句话摘要。

概要

这个小节包含该命令的语法表。概要通常应该不列出每个命令行选项;那些东西由后续小节介绍。概要应该列出命令行的主要部分,比如输入和输出文件会到哪里去。

描述

解释命令干什么的几个段落。

选项

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

退出状态

如果程序用 0 表示成功,非零表示失败,那么你不需要为此写文档。如果在每个非零退出码有不同的含义,那么在这里列出它们。

用法

描述程序的任意子语言或者运行时接口。如果程序不是交互式的,那么本节通常可以省略。否则,本节是全方位描述运行时特性的地方。如果需要可以使用子小节。

环境

列出所有程序可能使用的环境变量。尽量完整;即使是那些看起来很琐碎的变量,比如SHELL都可能让读者感兴趣。

文件

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

诊断

解释程序可能生成的任何不正常的输出。避免列出所有可能的错误消息。 这样做工作量很大但没有太多实际用处。但是如果错误消息有一种用户可以解析的标准格式,那么它应当在这里解释。

注意

任何放在其他地方都不合适的东西可以放在这里,但是特别是缺陷、实现瑕疵、安全考虑、兼容性问题。

例子

例子

历史

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

作者

作者(只在 contrib 节中使用)

另见

交叉引用,按照下面的顺序列出:其它PostgreSQL命令参考页、PostgreSQL SQL命令参考页、引用PostgreSQL手册、 其它参考页(如操作系统、其它包)、其它文档。在同一组中的项按照字母表顺序列出。

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