B.5. 风格指导

B.5.1. 参考页

参考页应该遵循标准的布局。这样就允许用户更快地找出自己需要 的信息,并且也可以鼓励作者把一条命令的所有相关方面都记录在案。 一致性不仅仅是 PostgreSQL 参考页的 需求,也是操作系统和其他页面提供的东西。 因此我们设计了下面的指导方针。它们在大多数时候是与各种操作系统 建立起来的类似的风格是一致的。

描述可执行命令的参考页应该包含下面的小节,并且是按照这里的顺序。 不适用的小节可以忽略。额外的顶级小节应该只用在特殊的环境下; 通常那些信息属于"用法"小节。 (译注:在中文man计划中,基本上也按照下列术语翻译,因此在此我们 将所有术语翻译成中文。--- laser)

名字

这个小节是自动生成的。它包含命令名和一个半句话的摘要, 介绍该命令的功能。

大纲

这个小节包含该命令的语法图表。大纲通常不应该列出每个命令行选项; 那些东西在后面做。大纲应该列出命令行的主要组件,比如应该把输入和 输出文件放在哪里等。

描述

几个段落,用于描述该命令是做什么的。

选项

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

退出状态

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

用法

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

环境

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

文件

列出所有程序可能隐含访问的文件。也就是说,不要列出在命令行上声明的 输入和输出文件。但是列出配置文件等等。

诊断

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

注意

任何在其他地方放都不合适的东西,尤其是虫虫,实现缺陷, 安全考量,兼容性问题等。

例子

例子

历史

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

又见

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

描述 SQL 命令的参考页应该包含下面的小节:名字,大纲,描述, 参数,用法,诊断,注意,例子,兼容性,历史,又见。 参数小节类似选项小节,但是我们有更多自由可以选择该命令的 哪个子句可以列出。兼容性小节应该解释此命令遵循 SQL 标准的哪个扩展, 或者它兼容哪种其他数据库系统。SQL 命令的“又见”小节应该在交叉 引用其他程序之前列出 SQL 命令。