begriffs open source - ai-pg/blob - full-docs/src/sgml/html/docguide-style.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.6. Style Guide</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-authoring.html" title="J.5. Documentation Authoring" /><link rel="next" href="limits.html" title="Appendix K. PostgreSQL Limits" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.6. Style Guide</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-authoring.html" title="J.5. Documentation Authoring">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="limits.html" title="Appendix K. PostgreSQL Limits">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-STYLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.6. Style Guide <a href="#DOCGUIDE-STYLE" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-style.html#DOCGUIDE-STYLE-REF-PAGES">J.6.1. Reference Pages</a></span></dt></dl></div><div class="sect2" id="DOCGUIDE-STYLE-REF-PAGES"><div class="titlepage"><div><div><h3 class="title">J.6.1. Reference Pages <a href="#DOCGUIDE-STYLE-REF-PAGES" class="id_link">#</a></h3></div></div></div><p>
   3     Reference pages should follow a standard layout.  This allows
   4     users to find the desired information more quickly, and it also
   5     encourages writers to document all relevant aspects of a command.
   6     Consistency is not only desired among
   7     <span class="productname">PostgreSQL</span> reference pages, but also
   8     with reference pages provided by the operating system and other
   9     packages.  Hence the following guidelines have been developed.
  10     They are for the most part consistent with similar guidelines
  11     established by various operating systems.
  12    </p><p>
  13     Reference pages that describe executable commands should contain
  14     the following sections, in this order.  Sections that do not apply
  15     can be omitted.  Additional top-level sections should only be used
  16     in special circumstances; often that information belongs in the
  17     <span class="quote">“<span class="quote">Usage</span>”</span> section.
  18
  19     </p><div class="variablelist"><dl class="variablelist"><dt id="DOCGUIDE-STYLE-REF-PAGES-NAME"><span class="term">Name</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-NAME" class="id_link">#</a></dt><dd><p>
  20         This section is generated automatically.  It contains the
  21         command name and a half-sentence summary of its functionality.
  22        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-SYNOPSIS"><span class="term">Synopsis</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-SYNOPSIS" class="id_link">#</a></dt><dd><p>
  23         This section contains the syntax diagram of the command.  The
  24         synopsis should normally not list each command-line option;
  25         that is done below.  Instead, list the major components of the
  26         command line, such as where input and output files go.
  27        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-DESCRIPTION"><span class="term">Description</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-DESCRIPTION" class="id_link">#</a></dt><dd><p>
  28         Several paragraphs explaining what the command does.
  29        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-OPTIONS"><span class="term">Options</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-OPTIONS" class="id_link">#</a></dt><dd><p>
  30         A list describing each command-line option.  If there are a
  31         lot of options, subsections can be used.
  32        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-EXIT-STATUS"><span class="term">Exit Status</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-EXIT-STATUS" class="id_link">#</a></dt><dd><p>
  33         If the program uses 0 for success and non-zero for failure,
  34         then you do not need to document it.  If there is a meaning
  35         behind the different non-zero exit codes, list them here.
  36        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-USAGE"><span class="term">Usage</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-USAGE" class="id_link">#</a></dt><dd><p>
  37         Describe any sublanguage or run-time interface of the program.
  38         If the program is not interactive, this section can usually be
  39         omitted.  Otherwise, this section is a catch-all for
  40         describing run-time features.  Use subsections if appropriate.
  41        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-ENVIRONMENT"><span class="term">Environment</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-ENVIRONMENT" class="id_link">#</a></dt><dd><p>
  42         List all environment variables that the program might use.
  43         Try to be complete; even seemingly trivial variables like
  44         <code class="envar">SHELL</code> might be of interest to the user.
  45        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-FILES"><span class="term">Files</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-FILES" class="id_link">#</a></dt><dd><p>
  46         List any files that the program might access implicitly.  That
  47         is, do not list input and output files that were specified on
  48         the command line, but list configuration files, etc.
  49        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-DIAGNOSTICS"><span class="term">Diagnostics</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-DIAGNOSTICS" class="id_link">#</a></dt><dd><p>
  50         Explain any unusual output that the program might create.
  51         Refrain from listing every possible error message.  This is a
  52         lot of work and has little use in practice.  But if, say, the
  53         error messages have a standard format that the user can parse,
  54         this would be the place to explain it.
  55        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-NOTES"><span class="term">Notes</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-NOTES" class="id_link">#</a></dt><dd><p>
  56         Anything that doesn't fit elsewhere, but in particular bugs,
  57         implementation flaws, security considerations, compatibility
  58         issues.
  59        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-EXAMPLES"><span class="term">Examples</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-EXAMPLES" class="id_link">#</a></dt><dd><p>
  60         Examples
  61        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-HISTORY"><span class="term">History</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-HISTORY" class="id_link">#</a></dt><dd><p>
  62         If there were some major milestones in the history of the
  63         program, they might be listed here.  Usually, this section can
  64         be omitted.
  65        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-AUTHOR"><span class="term">Author</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-AUTHOR" class="id_link">#</a></dt><dd><p>
  66         Author (only used in the contrib section)
  67        </p></dd><dt id="DOCGUIDE-STYLE-REF-PAGES-SEE-ALSO"><span class="term">See Also</span> <a href="#DOCGUIDE-STYLE-REF-PAGES-SEE-ALSO" class="id_link">#</a></dt><dd><p>
  68         Cross-references, listed in the following order: other
  69         <span class="productname">PostgreSQL</span> command reference pages,
  70         <span class="productname">PostgreSQL</span> SQL command reference
  71         pages, citation of <span class="productname">PostgreSQL</span>
  72         manuals, other reference pages (e.g., operating system, other
  73         packages), other documentation.  Items in the same group are
  74         listed alphabetically.
  75        </p></dd></dl></div><p>
  76    </p><p>
  77     Reference pages describing SQL commands should contain the
  78     following sections: Name, Synopsis, Description, Parameters,
  79     Outputs, Notes, Examples, Compatibility, History, See
  80     Also.  The Parameters section is like the Options section, but
  81     there is more freedom about which clauses of the command can be
  82     listed.  The Outputs section is only needed if the command returns
  83     something other than a default command-completion tag.  The Compatibility
  84     section should explain to what extent
  85     this command conforms to the SQL standard(s), or to which other
  86     database system it is compatible.  The See Also section of SQL
  87     commands should list SQL commands before cross-references to
  88     programs.
  89    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-authoring.html" title="J.5. Documentation Authoring">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="limits.html" title="Appendix K. PostgreSQL Limits">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.5. Documentation Authoring </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix K. <span class="productname">PostgreSQL</span> Limits</td></tr></table></div></body></html>