postgresql/doc/src/sgml/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
   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-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>
    To build 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 html</userinput>
</screen>
    For a list of other documentation targets see
    <xref linkend="targets-meson-documentation"/>.

    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>