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