docguide.sgml

<!-- doc/src/sgml/docguide.sgml -->

<appendix id="docguide">
 <title>Documentation</title>

 <para>
  <productname>PostgreSQL</productname> has four primary documentation
  formats:

  <itemizedlist>
   <listitem>
    <para>
     Plain text, for pre-installation information
    </para>
   </listitem>
   <listitem>
    <para>
     <acronym>HTML</acronym>, for on-line browsing and reference
    </para>
   </listitem>
   <listitem>
    <para>
     PDF, for printing
    </para>
   </listitem>
   <listitem>
    <para>
     man pages, for quick reference.
    </para>
   </listitem>
  </itemizedlist>

  Additionally, a number of plain-text <filename>README</filename> files can
  be found throughout the <productname>PostgreSQL</productname> source tree,
  documenting various implementation issues.
 </para>

 <para>
  <acronym>HTML</acronym> documentation and man pages are part of a
  standard distribution and are installed by default.  PDF
  format documentation is available separately for
  download.
 </para>

 <sect1 id="docguide-docbook">
  <title>DocBook</title>
  <para>
   The documentation sources are written in
   <firstterm>DocBook</firstterm>, which is a markup language
   superficially similar to <acronym>HTML</acronym>.  Both of these
   languages are applications of the <firstterm>Standard Generalized
   Markup Language</firstterm>, <acronym>SGML</acronym>, which is
   essentially a language for describing other languages.  In what
   follows, the terms DocBook and <acronym>SGML</acronym> are both
   used, but technically they are not interchangeable.
  </para>

  <note>
   <para>
    The PostgreSQL documentation is currently being transitioned from DocBook
    SGML and DSSSL style sheets to DocBook XML and XSLT style sheets.  Be
    careful to look at the instructions relating to the PostgreSQL version you
    are dealing with, as the procedures and required tools will change.
   </para>
  </note>

  <para>
  <productname>DocBook</productname> allows an author to specify the
   structure and content of a technical document without worrying
   about presentation details.  A document style defines how that
   content is rendered into one of several final forms.  DocBook is
   maintained by the <ulink url="http://www.oasis-open.org">
   OASIS group</ulink>.  The <ulink url="http://www.oasis-open.org/docbook/">
   official DocBook site</ulink> has good introductory and reference documentation and
   a complete O'Reilly book for your online reading pleasure.  The
   <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
   NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
   The <ulink url="http://www.freebsd.org/docproj/docproj.html">
   FreeBSD Documentation Project</ulink> also uses DocBook and has some good
   information, including a number of style guidelines that might be
   worth considering.
  </para>
 </sect1>


 <sect1 id="docguide-toolsets">
  <title>Tool Sets</title>

  <para>
   The following tools are used to process the documentation.  Some
   might be optional, as noted.

   <variablelist>
    <varlistentry>
     <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
     <listitem>
      <para>
       This is the definition of DocBook itself.  We currently use version
       4.2; you cannot use later or earlier versions.  You need
       the <acronym>SGML</acronym> and the <acronym>XML</acronym> variant of
       the DocBook DTD of the same version.  These will usually be in separate
       packages.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
     <listitem>
      <para>
       These are required by DocBook SGML but are distributed separately
       because they are maintained by ISO.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
     <listitem>
      <para>
       These contain the processing instructions for converting the
       DocBook sources to other formats, such as
       <acronym>HTML</acronym>.
      </para>

      <para>
       The minimum required version is currently 1.77.0, but it is recommended
       to use the latest available version for best results.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://openjade.sourceforge.net">OpenSP</ulink></term>
     <listitem>
      <para>
       This is the base package of <acronym>SGML</acronym> processing.  Note
       that we no longer need OpenJade, the <acronym>DSSSL</acronym>
       processor, only the OpenSP package for converting SGML to XML.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
     <listitem>
      <para>
       This library and the <command>xmllint</command> tool it contains are
       used for processing XML.  Many developers will already
       have <application>Libxml2</application> installed, because it is also
       used when building the PostgreSQL code.  Note, however,
       that <command>xmllint</command> might need to be installed from a
       separate subpackage.
      </para>
     </listitem>
     </varlistentry>

    <varlistentry>
     <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
     <listitem>
      <para>
       <command>xsltproc</command> is an XSLT processor, that is, a program to
       convert XML to other formats using XSLT stylesheets.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term>
     <listitem>
      <para>
       This is a program for converting, among other things, XML to PDF.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   We have documented experience with several installation methods for
   the various tools that are needed to process the documentation.
   These will be described below.  There might be some other packaged
   distributions for these tools. Please report package status to the
   documentation mailing list, and we will include that information
   here.
  </para>

  <para>
   You can get away with not installing DocBook XML and the DocBook XSLT
   stylesheets locally, because the required files will be downloaded from the
   Internet and cached locally.  This may in fact be the preferred solution if
   your operating system packages provide only an old version of especially
   the stylesheets or if no packages are available at all.  See
   the <option>--nonet</option> option for <command>xmllint</command>
   and <command>xsltproc</command> for more information.
  </para>

  <sect2>
   <title>Installation on Fedora, RHEL, and Derivatives</title>

   <para>
    To install the required packages, use:
<programlisting>
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Installation on FreeBSD</title>

   <para>
    The FreeBSD Documentation Project is itself a heavy user of
    DocBook, so it comes as no surprise that there is a full set of
    <quote>ports</quote> of the documentation tools available on
    FreeBSD.  The following ports need to be installed to build the
    documentation on FreeBSD.
    <itemizedlist>
     <listitem>
      <para><filename>textproc/docbook-sgml</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/docbook-xml</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/docbook-xsl</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/dsssl-docbook-modular</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/libxslt</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/fop</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/opensp</filename></para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    To install the required packages with <command>pkg</command>, use:
<programlisting>
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
</programlisting>
   </para>

   <para>
    When building the documentation from the <filename>doc</filename>
    directory you'll need to use <command>gmake</command>, because the
    makefile provided is not suitable for FreeBSD's <command>make</command>.
   </para>

   <para>
    More information about the FreeBSD documentation tools can be
    found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
    FreeBSD Documentation Project's instructions</ulink>.
   </para>
  </sect2>

  <sect2>
   <title>Debian Packages</title>

   <para>
    There is a full set of packages of the documentation tools
    available for <productname>Debian GNU/Linux</productname>.
    To install, simply use:
<programlisting>
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>macOS</title>

   <para>
    If you use MacPorts, the following will get you set up:
<programlisting>
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Manual Installation from Source</title>

   <para>
    The manual installation process of the DocBook tools is somewhat
    complex, so if you have pre-built packages available, use them.
    We describe here only a standard setup, with reasonably standard
    installation paths, and no <quote>fancy</quote> features.  For
    details, you should study the documentation of the respective
    package, and read <acronym>SGML</acronym> introductory material.
   </para>

   <sect3>
    <title>Installing OpenSP</title>

    <para>
     The installation of OpenSP offers a GNU-style
     <literal>./configure; make; make install</literal> build process.
     Details can be found in the OpenSP source distribution. In a nutshell:
<synopsis>
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog
make
make install
</synopsis>
     Be sure to remember where you put the <quote>default catalog</quote>; you
     will need it below.  You can also leave it off, but then you will have to
     set the environment variable <envar>SGML_CATALOG_FILES</envar> to point
     to the file whenever you use any programs from OpenSP later on.  (This
     method is also an option if OpenSP is already installed and you want to
     install the rest of the toolchain locally.)
    </para>
   </sect3>

   <sect3>
    <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>

    <procedure>
     <step>
      <para>
       Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
       DocBook V4.2 distribution</ulink>.
      </para>
     </step>

     <step>
      <para>
       Create the directory
       <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
       to it. (The exact location is irrelevant, but this one is
       reasonable within the layout we are following here.)
<screen>
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
</screen>
      </para>
     </step>

     <step>
      <para>
       Unpack the archive:
<screen>
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
</screen>
       (The archive will unpack its files into the current directory.)
      </para>
     </step>

     <step>
      <para>
       Edit the file
       <filename>/usr/local/share/sgml/catalog</filename> (or whatever
       you told jade during installation) and put a line like this
       into it:
<programlisting>
CATALOG "docbook-4.2/docbook.cat"
</programlisting>
      </para>
     </step>

     <step>
      <para>
       Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
       ISO 8879 character entities archive</ulink>, unpack it, and put the
       files in the same directory you put the DocBook files in:
<screen>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
</screen>
      </para>
     </step>

     <step>
      <para>
       Run the following command in the directory with the DocBook and ISO files:
<programlisting>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
       (This fixes a mixup between the names used in the DocBook
       catalog file and the actual names of the ISO character entity
       files.)
      </para>
     </step>
    </procedure>
   </sect3>
  </sect2>

  <sect2 id="docguide-toolsets-configure">
   <title>Detection by <command>configure</command></title>

  <para>
   Before you can build the documentation you need to run the
   <filename>configure</filename> script as you would when building
   the <productname>PostgreSQL</productname> programs themselves.
   Check the output near the end of the run, it should look something
   like this:
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop
</computeroutput>
</screen>
   If neither <filename>onsgmls</filename> nor
   <filename>nsgmls</filename> were found then some of the following tests
   will be skipped.  <filename>nsgmls</filename> is part of the OpenSP
   package.  You can pass the environment variable
   <envar>NSGMLS</envar> to configure to point
   to the programs if they are not found automatically.  If
   <quote>DocBook V4.2</quote> was not found then you did not install
   the DocBook DTD kit in a place where OpenSP can find it, or you have
   not set up the catalog files correctly.  See the installation hints
   above.
  </para>

  </sect2>
 </sect1>

 <sect1 id="docguide-build">
  <title>Building The Documentation</title>

  <para>
   Once you have everything set up, change to the directory
   <filename>doc/src/sgml</filename> and run one of the commands
   described in the following subsections to build the
   documentation. (Remember to use GNU make.)
  </para>

  <sect2>
   <title>HTML</title>

   <para>
    To build the <acronym>HTML</acronym> version of the documentation:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
</screen>
    This is also the default target.  The output appears in the
    subdirectory <filename>html</filename>.
   </para>

   <para>
    To produce HTML documentation with the stylesheet used on <ulink
    url="https://www.postgresql.org/docs/current">postgresql.org</> instead of the
    default simple style use:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
</screen>
   </para>
 </sect2>

 <sect2>
  <title>Manpages</title>

  <para>
   We use the DocBook XSL stylesheets to
   convert <productname>DocBook</productname>
   <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
   pages.  The man pages are also distributed as a tar archive,
   similar to the <acronym>HTML</acronym> version.  To create the man
   pages, use the commands:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
</screen>
  </para>
 </sect2>

  <sect2>
   <title>PDF</title>

   <para>
    To produce a PDF rendition of the documentation
    using <productname>FOP</productname>, you can use one of the following
    commands, depending on the preferred paper format:

    <itemizedlist>
     <listitem>
      <para>
       For A4 format:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
</screen>
      </para>
     </listitem>

     <listitem>
      <para>
       For U.S. letter format:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
</screen>
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    Because the PostgreSQL documentation is fairly
    big, <productname>FOP</productname> will require a significant amount of
    memory.  Because of that, on some systems, the build will fail with a
    memory-related error message.  This can usually be fixed by configuring
    Java heap settings in the configuration
    file <filename>~/.foprc</filename>, for example:
<programlisting>
# FOP binary distribution
FOP_OPTS='-Xmx1000m'
# Debian
JAVA_ARGS='-Xmx1000m'
# Red Hat
ADDITIONAL_FLAGS='-Xmx1000m'
</programlisting>
    There is a minimum amount of memory that is required, and to some extent
    more memory appears to make things a bit faster.  On systems with very
    little memory (less than 1 GB), the build will either be very slow due to
    swapping or will not work at all.
   </para>

   <para>
    Other XSL-FO processors can also be used manually, but the automated build
    process only supports FOP.
   </para>
  </sect2>

  <sect2>
   <title>Plain Text Files</title>

   <para>
    The installation instructions are also distributed as plain text,
    in case they are needed in a situation where better reading tools
    are not available.  The <filename>INSTALL</filename> file
    corresponds to <xref linkend="installation">, with some minor
    changes to account for the different context.  To recreate the
    file, change to the directory <filename>doc/src/sgml</filename>
    and enter <userinput>make INSTALL</userinput>.
   </para>

   <para>
    In the past, the release notes and regression testing instructions
    were also distributed as plain text, but this practice has been
    discontinued.
   </para>
  </sect2>

  <sect2>
   <title>Syntax Check</title>

   <para>
    Building the documentation can take very long.  But there is a
    method to just check the correct syntax of the documentation
    files, which only takes a few seconds:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
</screen>
   </para>
  </sect2>
 </sect1>


 <sect1 id="docguide-authoring">
  <title>Documentation Authoring</title>

   <para>
    <acronym>SGML</acronym> and <productname>DocBook</productname> do
    not suffer from an oversupply of open-source authoring tools. The
    most common tool set is the
    <productname>Emacs</productname>/<productname>XEmacs</productname>
    editor with appropriate editing mode.  On some systems
    these tools are provided in a typical full installation.
   </para>

   <sect2>
    <title>Emacs/PSGML</title>

    <para>
     <productname>PSGML</productname> is the most common and most
     powerful mode for editing <acronym>SGML</acronym> documents.
     When properly configured, it will allow you to use
     <application>Emacs</application> to insert tags and check markup
     consistency.  You could use it for <acronym>HTML</acronym> as
     well.  Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
     PSGML web site</ulink> for downloads, installation instructions, and
     detailed documentation.
    </para>

    <para>
     There is one important thing to note with
     <productname>PSGML</productname>: its author assumed that your
     main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
     would be <filename>/usr/local/lib/sgml</filename>.  If, as in the
     examples in this chapter, you use
     <filename>/usr/local/share/sgml</filename>, you have to
     compensate for this, either by setting
     <envar>SGML_CATALOG_FILES</envar> environment variable, or you
     can customize your <productname>PSGML</productname> installation
     (its manual tells you how).
    </para>

    <para>
     Put the following in your <filename>~/.emacs</filename>
     environment file (adjusting the path names to be appropriate for
     your system):

<programlisting>
; ********** for SGML mode (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>

     and in the same file add an entry for <acronym>SGML</acronym>
     into the (existing) definition for
     <varname>auto-mode-alist</varname>:
<programlisting>
(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))
</programlisting>
    </para>

    <para>
     You might find that when using <productname>PSGML</productname>, a
     comfortable way of working with these separate files of book
     parts is to insert a proper <literal>DOCTYPE</literal>
     declaration while you're editing them.  If you are working on
     this source, for instance, it is an appendix chapter, so you
     would specify the document as an <quote>appendix</quote> instance
     of a DocBook document by making the first line look like this:

<programlisting>
&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;
</programlisting>

     This means that anything and everything that reads
     <acronym>SGML</acronym> will get it right, and I can verify the
     document with <command>nsgmls -s docguide.sgml</command>.  (But
     you need to take out that line before building the entire
     documentation set.)
    </para>
   </sect2>

   <sect2>
    <title>Other Emacs Modes</title>

    <para>
     <productname>GNU Emacs</productname> ships with a different
     <acronym>SGML</acronym> mode, which is not quite as powerful as
     <productname>PSGML</productname>, but it's less confusing and
     lighter weight.  Also, it offers syntax highlighting (font lock),
     which can be very helpful.
     <filename>src/tools/editors/emacs.samples</filename> contains
     sample settings for this mode.
    </para>

    <para>
     Norm Walsh offers a
     <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
     specifically for DocBook which also has font-lock and a number of features to
     reduce typing.
    </para>
   </sect2>

 </sect1>


 <sect1 id="docguide-style">
  <title>Style Guide</title>

  <sect2>
   <title>Reference Pages</title>

   <para>
    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
    <productname>PostgreSQL</productname> 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.
   </para>

   <para>
    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
    <quote>Usage</quote> section.

    <variablelist>
     <varlistentry>
      <term>Name</term>
      <listitem>
       <para>
        This section is generated automatically.  It contains the
        command name and a half-sentence summary of its functionality.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Synopsis</term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Description</term>
      <listitem>
       <para>
        Several paragraphs explaining what the command does.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Options</term>
      <listitem>
       <para>
        A list describing each command-line option.  If there are a
        lot of options, subsections can be used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Exit Status</term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Usage</term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Environment</term>
      <listitem>
       <para>
        List all environment variables that the program might use.
        Try to be complete; even seemingly trivial variables like
        <envar>SHELL</envar> might be of interest to the user.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Files</term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Diagnostics</term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Notes</term>
      <listitem>
       <para>
        Anything that doesn't fit elsewhere, but in particular bugs,
        implementation flaws, security considerations, compatibility
        issues.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Examples</term>
      <listitem>
       <para>
        Examples
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>History</term>
      <listitem>
       <para>
        If there were some major milestones in the history of the
        program, they might be listed here.  Usually, this section can
        be omitted.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Author</term>
      <listitem>
       <para>
        Author (only used in the contrib section)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>See Also</term>
      <listitem>
       <para>
        Cross-references, listed in the following order: other
        <productname>PostgreSQL</productname> command reference pages,
        <productname>PostgreSQL</productname> SQL command reference
        pages, citation of <productname>PostgreSQL</productname>
        manuals, other reference pages (e.g., operating system, other
        packages), other documentation.  Items in the same group are
        listed alphabetically.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    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.
   </para>
  </sect2>

 </sect1>
</appendix>