# J.5.风格指南
# J.5.1.参考页
参考页应遵循标准布局。这允许用户更快地找到所需的信息,还鼓励编写者记录命令的所有相关方面。不仅需要PostgreSQL参考页之间的一致性,还需要操作系统和其他软件包提供的参考页之间的一致性。因此,制定了以下指南。它们在很大程度上符合各种操作系统制定的类似指南。
描述可执行命令的参考页应按以下顺序包含以下部分。不适用的部分可以省略。只有在特殊情况下才能使用额外的顶层部分;这些信息通常属于“用法”部分。
名称
此部分是自动生成的。它包含命令名及其功能的半句总结。
提要
本节包含该命令的语法图。大纲通常不应列出每个命令行选项;这是在下面完成的。相反,请列出命令行的主要组件,例如输入和输出文件的位置。
描述
几个段落解释了该命令的作用。
选项
描述每个命令行选项的列表。如果有很多选择,可以使用小节。
退出状态
如果程序使用0表示成功,使用非零表示失败,则无需对其进行记录。如果不同的非零退出代码背后有什么含义,请在此处列出。
用法
描述程序的任何子语言或运行时接口。如果程序不是交互式的,这一部分通常可以省略。否则,本节将是描述运行时特性的总括。如果合适,使用小节。
环境
列出程序可能使用的所有环境变量。努力做到完整;甚至看似微不足道的变量,比如壳
用户可能感兴趣。
文件夹
列出程序可能隐式访问的所有文件。也就是说,不要列出在命令行上指定的输入和输出文件,而是列出配置文件等。
诊断学
解释程序可能产生的任何异常输出。不要列出所有可能的错误信息。这是大量的工作,在实践中几乎没有用处。但是,如果,比如说,错误消息有一个用户可以解析的标准格式,这将是解释它的地方。
笔记
任何不适合其他地方的东西,尤其是bug、实现缺陷、安全考虑、兼容性问题。
例子
例子
历史
如果该项目的历史上有一些重要的里程碑,它们可能会列在这里。通常,这一部分可以省略。
著者
作者(仅用于contrib部分)
另见
交叉引用,按以下顺序列出:其他PostgreSQL命令参考页、PostgreSQL命令参考页、PostgreSQL手册引用、其他参考页(如操作系统、其他软件包)、其他文档。同一组中的项目按字母顺序列出。
描述SQL命令的参考页应包含以下部分:名称、概要、描述、参数、输出、注释、示例、兼容性、历史,另请参见。Parameters部分与Options部分类似,但对于可以列出命令的哪些子句有更多的自由。只有当命令返回的不是默认的命令完成标记时,才需要Outputs部分。兼容性部分应解释此命令在多大程度上符合SQL标准,或与哪个其他数据库系统兼容。SQL命令的“另请参见”部分应在交叉引用程序之前列出SQL命令。