参考页应遵循标准布局。这使用户可以更快速地查找所需信息,并且还鼓励作者记录命令的所有相关方面。一致性不仅在 PostgreSQL 参考页中受到重视,在操作系统和其他包提供的参考页中也备受重视。因此制定了以下指南。它们在大部分方面与各种操作系统制定的类似指南一致。
描述可执行命令的参考页应按照此顺序包含以下部分。不适用的部分可被省略。只有在特殊情况下才应使用其他顶级部分;这些信息通常属于 “用法” 部分。
此部分自动生成。此部分包含命令名称及其实用程序功能的半句总结。
此部分包含命令的语法图。该概要通常不应列出每个命令行选项;该操作将在下方完成。相反,列出命令行的主要组件,如输入和输出文件去往何处。
几个段落对命令的功能进行了详细说明。
列表中详述了每个命令行选项。如果有许多选项,可以使用子部分。
如果程序使用 0 表示成功,非零表示失败,那么您无需记录它。如果不同的非零退出代码后面有意义,请在此处列出这些代码。
描述程序的任何子语言或运行时接口。如果程序不是交互式的,则通常可以省略此部分。否则,此部分是对运行时功能进行描述的总汇。适当时,使用子部分。
列出程序可能使用的所有环境变量。尝试使其完整;即使是看似微不足道的变量,如 SHELL
也可能引起用户的兴趣。
列出程序可能隐式访问的任何文件。也就是说,不列出命令行上指定的输入和输出文件,但列出配置文件等。
解释该程序可能产生的所有异常输出。不要列出所有可能的错误信息。这是一件繁琐的事,而且在实践中鲜少会用到。但是,比如出现错误信息,并且用户可对错误信息进行分析,在此处则需要对其进行解释。
任何不适合放在其他位置的内容,但特别是 bug、实现缺陷、安全注意事项、兼容性问题。
示例
此处可能列出程序历史中的一些主要里程碑。该部分通常可以省略。
作者(仅在贡献部分中使用)
按以下顺序排列交叉引用:其他 PostgreSQL 命令参考页、PostgreSQL SQL 命令参考页、PostgreSQL 手册的引用、其他参考页(例如操作系统、其他软件包)、其他文档。同一组中的项目按字母顺序排列。
描述 SQL 命令的参考页应包含以下部分:名称、摘要、说明、参数、输出、注释、示例、兼容性、历史、参见。参数部分类似于选项部分,但可以更自由地选择命令的哪些子句。仅当命令返回除默认命令完成标记之外的其他内容时,才需要输出部分。兼容性部分应解释此命令在多大程度上符合 SQL 标准或与此兼容的其他数据库系统。SQL 命令的参见部分应在交叉引用程序之前列出 SQL 命令。