Split contrib documentation into extensions and programs

Create separate appendixes for contrib extensions and other server
plugins on the one hand, and utility programs on the other.  Recast
the documentation of the latter as refentries, so that man pages are
generated.

Author: petere

doc/src/sgml/contrib.sgml

@@ -4,7 +4,7 @@
  <title>Additional Supplied Modules</title>
 
  <para>
-  This appendix contains information regarding the modules that
+  This appendix and the next one contain information regarding the modules that
   can be found in the <literal>contrib</literal> directory of the
   <productname>PostgreSQL</> distribution.
   These include porting tools, analysis utilities,
@@ -15,7 +15,13 @@
  </para>
 
  <para>
-  When building from the source distribution, these modules are not built
+  This appendix covers extensions and other server plug-in modules found in
+  <literal>contrib</literal>.  <xref linkend="contrib-prog"> covers utility
+  programs.
+ </para>
+
+ <para>
+  When building from the source distribution, these components are not built
   automatically, unless you build the "world" target
   (see <xref linkend="build">).
   You can build and install all of them by running:
@@ -88,6 +94,14 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
   <xref linkend="extend-extensions">.
  </para>
 
+ <para>
+  Note, however, that some of these modules are not <quote>extensions</quote>
+  in this sense, but are loaded into the server in some other way, for instance
+  by way of
+  <xref linkend="guc-shared-preload-libraries">.  See the documentation of each
+  module for details.
+ </para>
+
  &adminpack;
  &auth-delay;
  &auto-explain;
@@ -109,22 +123,15 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
  &isn;
  &lo;
  &ltree;
- &oid2name;
  &pageinspect;
  &passwordcheck;
- &pgarchivecleanup;
- &pgbench;
  &pgbuffercache;
  &pgcrypto;
  &pgfreespacemap;
  &pgrowlocks;
- &pgstandby;
  &pgstatstatements;
  &pgstattuple;
- &pgtestfsync;
- &pgtesttiming;
  &pgtrgm;
- &pgupgrade;
  &seg;
  &sepgsql;
  &contrib-spi;
@@ -135,7 +142,69 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
  &tsearch2;
  &unaccent;
  &uuid-ossp;
- &vacuumlo;
  &xml2;
 
 </appendix>
+
+<!--
+These are two separate appendixes because it is difficult to mix regular
+sections (for extensions) and refentries (for programs) in one chapter or
+appendix.  And we do want the programs as refentries so that we can produce man
+pages.
+-->
+
+<appendix id="contrib-prog">
+ <title>Additional Supplied Programs</title>
+
+ <para>
+  This appendix and the previous one contain information regarding the modules that
+  can be found in the <literal>contrib</literal> directory of the
+  <productname>PostgreSQL</> distribution.  See <xref linkend="contrib"> for
+  more information about the <literal>contrib</literal> section in general and
+  server extensions and plug-ins found in <literal>contrib</literal>
+  specifically.
+ </para>
+
+ <para>
+  This appendix covers utility programs found in <literal>contrib</literal>.
+  Once installed, either from source or a packaging system, they are found in
+  the <filename>bin</filename> directory of the
+  <productname>PostgreSQL</productname> installation and can be used like any
+  other program.
+ </para>
+
+ <sect1 id="contrib-prog-client">
+  <title>Client Applications</title>
+
+  <para>
+   This section covers <productname>PostgreSQL</productname> client
+   applications in <literal>contrib</literal>.  They can be run from anywhere,
+   independent of where the database server resides.  See
+   also <xref linkend="reference-client"> for information about client
+   applications that part of the core <productname>PostgreSQL</productname>
+   distribution.
+  </para>
+
+ &oid2name;
+ &pgbench;
+ &vacuumlo;
+ </sect1>
+
+ <sect1 id="contrib-prog-server">
+  <title>Server Applications</title>
+
+  <para>
+   This section covers <productname>PostgreSQL</productname> server-related
+   applications in <literal>contrib</literal>.  They are typically run on the
+   host where the database server resides.  See also <xref
+   linkend="reference-server"> for information about server applications that
+   part of the core <productname>PostgreSQL</productname> distribution.
+  </para>
+
+ &pgarchivecleanup;
+ &pgstandby;
+ &pgtestfsync;
+ &pgtesttiming;
+ &pgupgrade;
+ </sect1>
+</appendix>

doc/src/sgml/docguide.sgml

@@ -1240,6 +1240,15 @@ save_size.pdfjadetex = 15000
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>Author</term>
+      <listitem>
+       <para>
+        Author (only used in the contrib section)
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term>See Also</term>
       <listitem>

doc/src/sgml/oid2name.sgml

@@ -1,12 +1,31 @@
 <!-- doc/src/sgml/oid2name.sgml -->
 
-<sect1 id="oid2name" xreflabel="oid2name">
- <title>oid2name</title>
+<refentry id="oid2name">
+ <refmeta>
+  <refentrytitle>oid2name</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>oid2name</refname>
+  <refpurpose>resolve OIDs and file nodes in a <productname>PostgreSQL</productname> data directory</refpurpose>
+ </refnamediv>
 
  <indexterm zone="oid2name">
   <primary>oid2name</primary>
  </indexterm>
 
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>oid2name</command>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
  <para>
   <application>oid2name</> is a utility program that helps administrators to
   examine the file structure used by PostgreSQL.  To make use of it, you need
@@ -24,19 +43,16 @@
   </para>
  </note>
 
- <sect2>
-  <title>Overview</title>
-
   <para>
    <application>oid2name</application> connects to a target database and
    extracts OID, filenode, and/or table name information.  You can also have
    it show database OIDs or tablespace OIDs.
   </para>
 
- </sect2>
+ </refsect1>
 
- <sect2>
-  <title><application>oid2name</> Options</title>
+ <refsect1>
+  <title>Options</title>
 
   <para>
    <application>oid2name</application> accepts the following command-line arguments:
@@ -142,9 +158,19 @@
    OIDs.  Alternatively you can give <option>-s</> to get a tablespace
    listing.
   </para>
- </sect2>
+ </refsect1>
 
- <sect2>
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <application>oid2name</> requires a running database server with
+   non-corrupt system catalogs.  It is therefore of only limited use
+   for recovering from catastrophic database corruption situations.
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Examples</title>
 
 <screen>
@@ -265,24 +291,14 @@ From database "alvherre":
 ----------------------
     155156         foo
 </screen>
- </sect2>
-
- <sect2>
-  <title>Limitations</title>
-
-  <para>
-   <application>oid2name</> requires a running database server with
-   non-corrupt system catalogs.  It is therefore of only limited use
-   for recovering from catastrophic database corruption situations.
-  </para>
- </sect2>
+ </refsect1>
 
- <sect2>
+ <refsect1>
   <title>Author</title>
 
   <para>
    B. Palmer <email>bpalmer@crimelabs.net</email>
   </para>
- </sect2>
+ </refsect1>
 
-</sect1>
+</refentry>