Postgresql 中文操作指南

J.6. Style Guide #

J.6.1. Reference Pages #

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

Reference pages should follow a standard layout. This allows users to find the desired information more quickly, and it also encourages writers to document all relevant aspects of a command. Consistency is not only desired among PostgreSQL reference pages, but also with reference pages provided by the operating system and other packages. Hence the following guidelines have been developed. They are for the most part consistent with similar guidelines established by various operating systems.

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

Reference pages that describe executable commands should contain the following sections, in this order. Sections that do not apply can be omitted. Additional top-level sections should only be used in special circumstances; often that information belongs in the “Usage” section.

  • Name #

    • This section is generated automatically. It contains the command name and a half-sentence summary of its functionality.

  • Synopsis #

    • This section contains the syntax diagram of the command. The synopsis should normally not list each command-line option; that is done below. Instead, list the major components of the command line, such as where input and output files go.

  • Description #

    • Several paragraphs explaining what the command does.

  • Options #

    • A list describing each command-line option. If there are a lot of options, subsections can be used.

  • Exit Status #

    • If the program uses 0 for success and non-zero for failure, then you do not need to document it. If there is a meaning behind the different non-zero exit codes, list them here.

  • Usage #

    • Describe any sublanguage or run-time interface of the program. If the program is not interactive, this section can usually be omitted. Otherwise, this section is a catch-all for describing run-time features. Use subsections if appropriate.

  • Environment #

    • List all environment variables that the program might use. Try to be complete; even seemingly trivial variables like SHELL might be of interest to the user.

  • Files #

    • List any files that the program might access implicitly. That is, do not list input and output files that were specified on the command line, but list configuration files, etc.

  • Diagnostics #

    • Explain any unusual output that the program might create. Refrain from listing every possible error message. This is a lot of work and has little use in practice. But if, say, the error messages have a standard format that the user can parse, this would be the place to explain it.

  • Notes #

    • Anything that doesn’t fit elsewhere, but in particular bugs, implementation flaws, security considerations, compatibility issues.

  • Examples #

    • Examples

  • History #

    • If there were some major milestones in the history of the program, they might be listed here. Usually, this section can be omitted.

  • Author #

    • Author (only used in the contrib section)

  • See Also #

    • Cross-references, listed in the following order: other PostgreSQL command reference pages, PostgreSQL SQL command reference pages, citation of PostgreSQL manuals, other reference pages (e.g., operating system, other packages), other documentation. Items in the same group are listed alphabetically.

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

Reference pages describing SQL commands should contain the following sections: Name, Synopsis, Description, Parameters, Outputs, Notes, Examples, Compatibility, History, See Also. The Parameters section is like the Options section, but there is more freedom about which clauses of the command can be listed. The Outputs section is only needed if the command returns something other than a default command-completion tag. The Compatibility section should explain to what extent this command conforms to the SQL standard(s), or to which other database system it is compatible. The See Also section of SQL commands should list SQL commands before cross-references to programs.