Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 697 insertions, 0 deletions

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
new file mode 100644
index 0000000..fd72b39
--- /dev/null
+++ b/doc/src/sgml/docguide.sgml
@@ -0,0 +1,697 @@
+<!-- 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
+   defined in <acronym>XML</acronym>.  In what
+   follows, the terms DocBook and <acronym>XML</acronym> are both
+   used, but technically they are not interchangeable.
+  </para>
+
+  <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="https://www.oasis-open.org">
+   OASIS group</ulink>.  The <ulink url="https://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="https://www.freebsd.org/docproj/">
+   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 id="docguide-toolsets-docbook-dtd">
+     <term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
+     <listitem>
+      <para>
+       This is the definition of DocBook itself.  We currently use version
+       4.5; you cannot use later or earlier versions.  You need
+       the <acronym>XML</acronym> variant of the DocBook DTD, not
+       the <acronym>SGML</acronym> variant.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry id="docguide-toolsets-docbook-xsl">
+     <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 id="docguide-toolsets-libxml2">
+     <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 id="docguide-toolsets-libxslt">
+     <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 id="docguide-toolsets-fop">
+     <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.
+       It is needed only if you want to build the documentation in PDF format.
+      </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>
+
+  <sect2 id="docguide-toolsets-inst-fedora-et-al">
+   <title>Installation on Fedora, RHEL, and Derivatives</title>
+
+   <para>
+    To install the required packages, use:
+<programlisting>
+yum install docbook-dtds docbook-style-xsl libxslt fop
+</programlisting>
+   </para>
+  </sect2>
+
+  <sect2 id="docguide-toolsets-inst-freebsd">
+   <title>Installation on FreeBSD</title>
+
+   <para>
+    To install the required packages with <command>pkg</command>, use:
+<programlisting>
+pkg install docbook-xml docbook-xsl libxslt fop
+</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>
+  </sect2>
+
+  <sect2 id="docguide-toolsets-inst-debian">
+   <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-xml docbook-xsl libxml2-utils xsltproc fop
+</programlisting>
+   </para>
+  </sect2>
+
+  <sect2 id="docguide-toolsets-inst-macos">
+   <title>macOS</title>
+
+   <para>
+    If you use MacPorts, the following will get you set up:
+<programlisting>
+sudo port install docbook-xml docbook-xsl-nons libxslt fop
+</programlisting>
+    If you use Homebrew, use this:
+<programlisting>
+brew install docbook docbook-xsl libxslt fop
+</programlisting>
+   </para>
+
+   <para>
+    The Homebrew-supplied programs require the following environment variable
+    to be set.  For Intel based machines, use this:
+<programlisting>
+export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
+</programlisting>
+    On Apple Silicon based machines, use this:
+<programlisting>
+export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
+</programlisting>
+    Without it, <command>xsltproc</command> will throw errors like this:
+<programlisting>
+I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
+postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+...
+</programlisting>
+   </para>
+
+   <para>
+    While it is possible to use the Apple-provided versions
+    of <command>xmllint</command> and <command>xsltproc</command>
+    instead of those from MacPorts or Homebrew, you'll still need
+    to install the DocBook DTD and stylesheets, and set up a catalog
+    file that points to them.
+   </para>
+  </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>
+checking for xmllint... xmllint
+checking for xsltproc... xsltproc
+checking for fop... fop
+checking for dbtoepub... dbtoepub
+</screen>
+   If <filename>xmllint</filename> or <filename>xsltproc</filename> is not
+   found, you will not be able to build any of the documentation.
+   <filename>fop</filename> is only needed to build the documentation in
+   PDF format.
+   <filename>dbtoepub</filename> is only needed to build the documentation
+   in EPUB format.
+  </para>
+
+  <para>
+   If necessary, you can tell <filename>configure</filename> where to find
+   these programs, for example
+<screen>
+./configure ... XMLLINT=/opt/local/bin/xmllint ...
+</screen>
+  </para>
+
+  <para>
+   If you prefer to build <productname>PostgreSQL</productname> using
+   Meson, instead run <command>meson setup</command> as described in
+   <xref linkend="install-meson"/>, and then see
+   <xref linkend="docguide-build-meson"/>.
+  </para>
+  </sect2>
+ </sect1>
+
+ <sect1 id="docguide-build">
+  <title>Building the Documentation with Make</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 id="docguide-build-html">
+   <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</ulink> instead of the
+    default simple style use:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
+</screen>
+   </para>
+
+   <para>
+    If the <literal>STYLE=website</literal> option is used, the generated HTML
+    files include references to stylesheets hosted on <ulink
+    url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> and
+    require network access to view.
+   </para>
+ </sect2>
+
+ <sect2 id="docguide-build-manpages">
+  <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.  To create the man pages, use the command:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
+</screen>
+  </para>
+ </sect2>
+
+  <sect2 id="docguide-build-pdf">
+   <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='-Xmx1500m'
+# Debian
+JAVA_ARGS='-Xmx1500m'
+# Red Hat
+ADDITIONAL_FLAGS='-Xmx1500m'
+</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>
+    In its default configuration <productname>FOP</productname> will emit an
+    <literal>INFO</literal> message for each page. The log level can be
+    changed via <filename>~/.foprc</filename>:
+<programlisting>
+LOGCHOICE=-Dorg.apache.commons.logging.Log=&zwsp;org.apache.commons.logging.impl.SimpleLog
+LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
+</programlisting>
+   </para>
+
+   <para>
+    Other XSL-FO processors can also be used manually, but the automated build
+    process only supports FOP.
+   </para>
+  </sect2>
+
+  <sect2 id="docguide-build-plain-text">
+   <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>.  Building text output
+    requires <productname>Pandoc</productname> version 1.13 or newer as an
+    additional build tool.
+   </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 id="docguide-build-syntax-check">
+   <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-build-meson">
+  <title>Building the Documentation with Meson</title>
+
+   <para>
+    Two options are provided for building the documentation using Meson.
+    Change to the <filename>build</filename> directory before running
+    one of these commands, or add <option>-C build</option> to the command.
+   </para>
+
+   <para>
+    To build just the <acronym>HTML</acronym> version of the documentation:
+<screen>
+<prompt>build$ </prompt><userinput>ninja docs</userinput>
+</screen>
+    To build all forms of the documentation:
+<screen>
+<prompt>build$ </prompt><userinput>ninja alldocs</userinput>
+</screen>
+    The output appears in the
+    subdirectory <filename>build/doc/src/sgml</filename>.
+   </para>
+ </sect1>
+
+
+ <sect1 id="docguide-authoring">
+  <title>Documentation Authoring</title>
+
+   <para>
+    The documentation sources are most conveniently modified with an editor
+    that has a mode for editing XML, and even more so if it has some awareness
+    of XML schema languages so that it can know about
+    <productname>DocBook</productname> syntax specifically.
+   </para>
+
+   <para>
+    Note that for historical reasons the documentation source files are named
+    with an extension <filename>.sgml</filename> even though they are now XML
+    files.  So you might need to adjust your editor configuration to set the
+    correct mode.
+   </para>
+
+   <sect2 id="docguide-authoring-emacs">
+    <title>Emacs</title>
+
+    <para>
+     <productname>nXML Mode</productname>, which ships with
+     <productname>Emacs</productname>, is the most common mode for editing
+     <acronym>XML</acronym> documents with <productname>Emacs</productname>.
+     It will allow you to use <application>Emacs</application> to insert tags
+     and check markup consistency, and it supports
+     <productname>DocBook</productname> out of the box.  Check the <ulink
+     url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html">
+     nXML manual</ulink> for detailed documentation.
+    </para>
+
+    <para>
+     <filename>src/tools/editors/emacs.samples</filename> contains
+     recommended settings for this mode.
+    </para>
+   </sect2>
+
+ </sect1>
+
+
+ <sect1 id="docguide-style">
+  <title>Style Guide</title>
+
+  <sect2 id="docguide-style-ref-pages">
+   <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 id="docguide-style-ref-pages-name">
+      <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 id="docguide-style-ref-pages-synopsis">
+      <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 id="docguide-style-ref-pages-description">
+      <term>Description</term>
+      <listitem>
+       <para>
+        Several paragraphs explaining what the command does.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="docguide-style-ref-pages-options">
+      <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 id="docguide-style-ref-pages-exit-status">
+      <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 id="docguide-style-ref-pages-usage">
+      <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 id="docguide-style-ref-pages-environment">
+      <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 id="docguide-style-ref-pages-files">
+      <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 id="docguide-style-ref-pages-diagnostics">
+      <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 id="docguide-style-ref-pages-notes">
+      <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 id="docguide-style-ref-pages-examples">
+      <term>Examples</term>
+      <listitem>
+       <para>
+        Examples
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="docguide-style-ref-pages-history">
+      <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 id="docguide-style-ref-pages-author">
+      <term>Author</term>
+      <listitem>
+       <para>
+        Author (only used in the contrib section)
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="docguide-style-ref-pages-see-also">
+      <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>