Postgresql 中文操作指南

J.6. Style Guide #

J.6.1. Reference Pages #

参考页面应遵循标准布局。这使用户能够更快地找到所需信息，而且还能鼓励编写者记录命令的所有相关方面。一致性不仅仅是 PostgreSQL 参考页面所需要的，它也是操作系统和其他软件包所提供的页面所需要的。因此制定了以下准则。它们在很大程度上与各种操作系统制定的类似准则保持一致。

描述可执行命令的参考页面应按以下顺序包含下列部分。不适用的部分可以省略。其他顶级部分只能在特殊情况下使用；通常该信息属于“使用”部分。

  • Name #

    • 本部分由系统自动生成。它包含命令名称和功能的半句话摘要。

  • Synopsis #

    • 本部分包含命令的语法图。通常摘要中不应列出每个命令行选项；它下面会列出。相反，列出命令行的主要部分，例如，输入和输出文件的位置。

  • Description #

    • 包含解释命令执行的若干段落。

  • Options #

    • 描述每个命令行选项的列表。如果选项很多，可以使用子部分。

  • Exit Status #

    • 如果程序使用 0 表示成功且使用非零表示失败，则不需要记录它。如果不同的非零退出代码后面有意义，请在此处列出它们。

  • Usage #

    • 描述程序的任何子语言或运行时界面。如果程序不是交互式的，通常可以省略此部分。否则，本部分是一个描述运行时特性的备忘录。如果合适，可以使用子部分。

  • Environment #

    • 列出程序可能使用的所有环境变量。力求完整；即使像是 SHELL 这样的看似微不足道的变量也可能对用户感兴趣。

  • Files #

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

  • Diagnostics #

    • 解释程序可能创建的任何不寻常输出。不要列出每个可能的错误消息。这需要大量工作，并且在实践中用处不大。但如果（例如）错误消息具有用户可以解析的标准格式，那么这里将是解释它的位置。

  • Notes #

    • 任何不适合放在其他地方的内容，尤其是 bug、实现缺陷、安全考虑事项、兼容性问题。

  • Examples #

    • Examples

  • History #

    • 如果程序历史上有一些重大里程碑，则可以将它们列在这里。通常，可以省略本部分。

  • Author #

    • 作者（只在附加内容部分使用）

  • See Also #

    • 参考，按以下顺序列出：其他 PostgreSQL 命令参考页面、PostgreSQL SQL 命令参考页面、PostgreSQL 手册引文、其他参考页面（例如，操作系统、其他软件包）、其他文档。同一组中的项按字母顺序排列。

描述 SQL 命令的参考页面应包含以下部分：名称、概要、描述、参数、输出、注释、示例、兼容性、历史记录、另请参阅。参数部分类似于选项部分，但对于可以列出的命令子句有更多自由度。仅当命令返回的不仅仅是默认命令完成标签时才需要输出部分。兼容性部分应说明此命令在多大程度上符合 SQL 标准，或与其他哪些数据库系统兼容。SQL 命令的另请参阅部分应在引用程序之前列出 SQL 命令。