1#@!#!123s

: / usr / share / doc / postgresql-9.2.24 / html /
Filename : docguide-style.html
back
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Style Guide</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"><LINK
REL="NEXT"
TITLE="Acronyms"
HREF="acronyms.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2017-11-06T22:43:11"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix J. Documentation</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Acronyms"
HREF="acronyms.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-STYLE"
>J.5. Style Guide</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN155462"
>J.5.1. Reference Pages</A
></H2
><P
>    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
    <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> 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.
   </P
><P
>    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
    <SPAN
CLASS="QUOTE"
>"Usage"</SPAN
> section.

    <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Name</DT
><DD
><P
>        This section is generated automatically.  It contains the
        command name and a half-sentence summary of its functionality.
       </P
></DD
><DT
>Synopsis</DT
><DD
><P
>        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.
       </P
></DD
><DT
>Description</DT
><DD
><P
>        Several paragraphs explaining what the command does.
       </P
></DD
><DT
>Options</DT
><DD
><P
>        A list describing each command-line option.  If there are a
        lot of options, subsections can be used.
       </P
></DD
><DT
>Exit Status</DT
><DD
><P
>        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.
       </P
></DD
><DT
>Usage</DT
><DD
><P
>        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.
       </P
></DD
><DT
>Environment</DT
><DD
><P
>        List all environment variables that the program might use.
        Try to be complete; even seemingly trivial variables like
        <TT
CLASS="ENVAR"
>SHELL</TT
> might be of interest to the user.
       </P
></DD
><DT
>Files</DT
><DD
><P
>        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.
       </P
></DD
><DT
>Diagnostics</DT
><DD
><P
>        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.
       </P
></DD
><DT
>Notes</DT
><DD
><P
>        Anything that doesn't fit elsewhere, but in particular bugs,
        implementation flaws, security considerations, compatibility
        issues.
       </P
></DD
><DT
>Examples</DT
><DD
><P
>        Examples
       </P
></DD
><DT
>History</DT
><DD
><P
>        If there were some major milestones in the history of the
        program, they might be listed here.  Usually, this section can
        be omitted.
       </P
></DD
><DT
>Author</DT
><DD
><P
>        Author (only used in the contrib section)
       </P
></DD
><DT
>See Also</DT
><DD
><P
>        Cross-references, listed in the following order: other
        <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> command reference pages,
        <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> SQL command reference
        pages, citation of <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
        manuals, other reference pages (e.g., operating system, other
        packages), other documentation.  Items in the same group are
        listed alphabetically.
       </P
></DD
></DL
></DIV
><P>
   </P
><P
>    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.
   </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-authoring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="acronyms.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Documentation Authoring</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Acronyms</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>