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
may 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 may be used.
Exit Status
If the program uses 0 for success and non-zero for failure,
then you don't 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.
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.
Reference pages describing SQL commands should contain the
following sections: Name, Synopsis, Description, Parameters,
Usage, Diagnostics, 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 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.
