Doc reference of contrib modules - Mailing list pgsql-docs

Now that our /contrib documentation is in our SGML manual, I want to
update our docs to link to the actual contrib module documentation,
rather than just referencing contrib/module_name.  We used to have to do
that when we only had READMEs, but now we can do better.

Patch attached, and I have a github branch of this too:

    https://github.com/bmomjian/postgres/compare/master...contrib_links

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f994eac..2d053ee 100644
*** /tmp/pgdiff.21665/EgdqAa_datatype.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/GzEpPa_datatype.sgml    Mon Jan 24 15:04:28 2011
*************** a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
*** 3917,3925 ****
      <productname>PostgreSQL</productname> provides storage and comparison
      functions for UUIDs, but the core database does not include any
      function for generating UUIDs, because no single algorithm is well
!     suited for every application.  The contrib module
!     <filename>contrib/uuid-ossp</filename> provides functions that implement
!     several standard algorithms.
      Alternatively, UUIDs could be generated by client applications or
      other libraries invoked through a server-side function.
     </para>
--- 3917,3925 ----
      <productname>PostgreSQL</productname> provides storage and comparison
      functions for UUIDs, but the core database does not include any
      function for generating UUIDs, because no single algorithm is well
!     suited for every application.  The module
!     <link linkend="uuid-ossp">uuid-ossp</>
!     provides functions that implement several standard algorithms.
      Alternatively, UUIDs could be generated by client applications or
      other libraries invoked through a server-side function.
     </para>
diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
index 0f390f3..006a98f 100644
*** /tmp/pgdiff.21665/4PWjMc_diskusage.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/s8xDFc_diskusage.sgml    Mon Jan 24 15:04:28 2011
***************
*** 31,40 ****
    <para>
     You can monitor disk space in three ways:
     using the SQL functions listed in <xref linkend="functions-admin-dbsize">,
!    using the tools in <filename>contrib/oid2name</>, or
     using manual inspection of the system catalogs.
     The SQL functions are the easiest to use and are generally recommended.
-    <filename>contrib/oid2name</> is described in <xref linkend="oid2name">.
     The remainder of this section shows how to do it by inspection of the
     system catalogs.
    </para>
--- 31,39 ----
    <para>
     You can monitor disk space in three ways:
     using the SQL functions listed in <xref linkend="functions-admin-dbsize">,
!    using the <link linkend="oid2name">oid2name</> module, or
     using manual inspection of the system catalogs.
     The SQL functions are the easiest to use and are generally recommended.
     The remainder of this section shows how to do it by inspection of the
     system catalogs.
    </para>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index d884122..c672266 100644
*** /tmp/pgdiff.21665/Y2ePnb_high-availability.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/e9NdPb_high-availability.sgml    Mon Jan 24 15:04:28 2011
*************** primary_conninfo = 'host=192.168.1.50 po
*** 967,973 ****
      This was the only option available in versions 8.4 and below. In this
      setup, set <varname>standby_mode</> off, because you are implementing
      the polling required for standby operation yourself. See
!     contrib/pg_standby (<xref linkend="pgstandby">) for a reference
      implementation of this.
     </para>

--- 967,973 ----
      This was the only option available in versions 8.4 and below. In this
      setup, set <varname>standby_mode</> off, because you are implementing
      the polling required for standby operation yourself. See
!     <link linkend="pgstandby">pg_standby</> for a reference
      implementation of this.
     </para>

*************** if (!triggered)
*** 1027,1033 ****

     <para>
      A working example of a waiting <varname>restore_command</> is provided
!     as a <filename>contrib</> module named <application>pg_standby</>. It
      should be used as a reference on how to correctly implement the logic
      described above. It can also be extended as needed to support specific
      configurations and environments.
--- 1027,1033 ----

     <para>
      A working example of a waiting <varname>restore_command</> is provided
!     in <link linkend="pgstandby">pg_standby</>. It
      should be used as a reference on how to correctly implement the logic
      described above. It can also be extended as needed to support specific
      configurations and environments.
*************** if (!triggered)
*** 1542,1548 ****
      primary server and keep a query active for as long as needed to
      run queries on the standby. This prevents <command>VACUUM</> from removing
      recently-dead rows and so cleanup conflicts do not occur.
!     This could be done using <filename>contrib/dblink</> and
      <function>pg_sleep()</>, or via other mechanisms. If you do this, you
      should note that this will delay cleanup of dead rows on the primary,
      which may result in undesirable table bloat. However, the cleanup
--- 1542,1548 ----
      primary server and keep a query active for as long as needed to
      run queries on the standby. This prevents <command>VACUUM</> from removing
      recently-dead rows and so cleanup conflicts do not occur.
!     This could be done using <link linkend="dblink">dblink</> and
      <function>pg_sleep()</>, or via other mechanisms. If you do this, you
      should note that this will delay cleanup of dead rows on the primary,
      which may result in undesirable table bloat. However, the cleanup
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index a480a8d..df732ed 100644
*** /tmp/pgdiff.21665/kiDmXd_installation.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/wCiCGd_installation.sgml    Mon Jan 24 15:04:28 2011
*************** su - postgres
*** 1007,1014 ****
         <listitem>
          <para>
           Use the <ulink url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID
!          library</ulink> when building <filename>contrib/uuid-ossp</>.
!          The library provides functions to generate
           UUIDs.<indexterm><primary>UUID</primary></indexterm>
          </para>
         </listitem>
--- 1007,1014 ----
         <listitem>
          <para>
           Use the <ulink url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID
!          library</ulink> when building the <link linkend="uuid-ossp">uuid-ossp</>
!          module.  The library provides functions to generate
           UUIDs.<indexterm><primary>UUID</primary></indexterm>
          </para>
         </listitem>
*************** su - postgres
*** 1041,1049 ****
         <term><option>--with-libxslt</option></term>
         <listitem>
          <para>
!          Use libxslt when building <filename>contrib/xml2</>.
!          <filename>contrib/xml2</> relies on this library to perform
!          XSL transformations of XML.
          </para>
         </listitem>
        </varlistentry>
--- 1041,1049 ----
         <term><option>--with-libxslt</option></term>
         <listitem>
          <para>
!          Use libxslt when building the <link linkend="xml2">xml2</>
!          module.  <application>xml2</> relies on this library
!          to perform XSL transformations of XML.
          </para>
         </listitem>
        </varlistentry>
diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml
index ab43a53..5f2e8cb 100644
*** /tmp/pgdiff.21665/UATEod_lo.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/aHUtqd_lo.sgml    Mon Jan 24 15:04:28 2011
*************** CREATE TRIGGER t_raster BEFORE UPDATE OR
*** 99,105 ****

      <para>
       If you already have, or suspect you have, orphaned large objects, see the
!      <filename>contrib/vacuumlo</> module (<xref linkend="vacuumlo">) to help
       you clean them up.  It's a good idea to run <application>vacuumlo</>
       occasionally as a back-stop to the <function>lo_manage</> trigger.
      </para>
--- 99,105 ----

      <para>
       If you already have, or suspect you have, orphaned large objects, see the
!      <link linkend="vacuumlo">vacuumlo</> module to help
       you clean them up.  It's a good idea to run <application>vacuumlo</>
       occasionally as a back-stop to the <function>lo_manage</> trigger.
      </para>
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 693fce5..3227b09 100644
*** /tmp/pgdiff.21665/VG4oyb_queries.sgml    Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/9Zanlb_queries.sgml    Mon Jan 24 15:04:29 2011
*************** SELECT *
*** 686,693 ****
        AS t1(proname name, prosrc text)
      WHERE proname LIKE 'bytea%';
  </programlisting>
!      The <literal>dblink</> function executes a remote query (see
!      <filename>contrib/dblink</>).  It is declared to return
       <type>record</> since it might be used for any kind of query.
       The actual column set must be specified in the calling query so
       that the parser knows, for example, what <literal>*</> should
--- 686,693 ----
        AS t1(proname name, prosrc text)
      WHERE proname LIKE 'bytea%';
  </programlisting>
!      The <link linkend="CONTRIB-DBLINK">dblink</> function executes
!      a remote query.  It is declared to return
       <type>record</> since it might be used for any kind of query.
       The actual column set must be specified in the calling query so
       that the parser knows, for example, what <literal>*</> should
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
index bd9dfd1..5653ac9 100644
*** /tmp/pgdiff.21665/DLfzwa_recovery-config.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/z5SHZa_recovery-config.sgml    Mon Jan 24 15:04:29 2011
*************** restore_command = 'copy "C:\\server\\arc
*** 92,100 ****
          may be safely removed.
          This information can be used to truncate the archive to just the
          minimum required to support restart from the current restore.
!         The <application>pg_archivecleanup</> utility provided in
!         <literal>contrib</> (see <xref linkend="pgarchivecleanup">) serves as a
!         convenient target for <varname>archive_cleanup_command</> in typical
          single-standby configurations, for example:
  <programlisting> archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' </programlisting>
          Note however that if multiple standby servers are restoring from the
--- 92,99 ----
          may be safely removed.
          This information can be used to truncate the archive to just the
          minimum required to support restart from the current restore.
!         The <link linkend="pgarchivecleanup">pg_archivecleanup</> module
!         is often used in <varname>archive_cleanup_command</> for
          single-standby configurations, for example:
  <programlisting> archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' </programlisting>
          Note however that if multiple standby servers are restoring from the
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index eff5854..9bf81ed 100644
*** /tmp/pgdiff.21665/HBR3ke_create_opclass.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/NKWkpe_create_opclass.sgml    Mon Jan 24 15:04:29 2011
*************** CREATE OPERATOR CLASS <replaceable class
*** 276,283 ****

    <para>
     The following example command defines a GiST index operator class
!    for the data type <literal>_int4</> (array of <type>int4</type>).  See
!    <filename>contrib/intarray/</> for the complete example.
    </para>

  <programlisting>
--- 276,283 ----

    <para>
     The following example command defines a GiST index operator class
!    for the data type <literal>_int4</> (array of <type>int4</type>).  See the
!    <link linkend="intarray">intarray</> module for the complete example.
    </para>

  <programlisting>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 9b92bec..bd25f3e 100644
*** /tmp/pgdiff.21665/ZaVwod_runtime.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/TlmVvb_runtime.sgml    Mon Jan 24 15:04:29 2011
*************** $ <userinput>kill -INT `head -1 /usr/loc
*** 1502,1510 ****

     <listitem>
      <para>
!      The <filename>contrib</> function library
!      <link linkend="pgcrypto"><function>pgcrypto</function></link>
!      allows certain fields to be stored encrypted.
       This is useful if only some of the data is sensitive.
       The client supplies the decryption key and the data is decrypted
       on the server and then sent to the client.
--- 1502,1509 ----

     <listitem>
      <para>
!      The <link linkend="pgcrypto">pgcrypto</link>
!      module allows certain fields to be stored encrypted.
       This is useful if only some of the data is sensitive.
       The client supplies the decryption key and the data is decrypted
       on the server and then sent to the client.
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 1ca9308..592c16d 100644
*** /tmp/pgdiff.21665/jFDoZa_spi.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/NqidRa_spi.sgml    Mon Jan 24 15:04:29 2011
*************** INSERT INTO a SELECT * FROM a;
*** 3939,3946 ****
     using <function>SPI_exec</function> and returns the number of rows
     that were processed by the command.  You can find more complex
     examples for SPI in the source tree in
!    <filename>src/test/regress/regress.c</filename> and in
!    <filename>contrib/spi</filename>.
    </para>

  <programlisting>
--- 3939,3946 ----
     using <function>SPI_exec</function> and returns the number of rows
     that were processed by the command.  You can find more complex
     examples for SPI in the source tree in
!    <filename>src/test/regress/regress.c</filename> and in the
!    <link linkend="spi">contrib/spi</> module.
    </para>

  <programlisting>
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index ad9fba2..90cb629 100644
*** /tmp/pgdiff.21665/PN12Kc_storage.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/ZWZYFc_storage.sgml    Mon Jan 24 15:04:29 2011
*************** at the root.
*** 455,462 ****
  <para>
  See <filename>src/backend/storage/freespace/README</> for more details on
  how the <acronym>FSM</> is structured, and how it's updated and searched.
! The <filename>contrib/pg_freespacemap</> module can be used to examine the
! information stored in free space maps (see <xref linkend="pgfreespacemap">).
  </para>

  </sect1>
--- 455,462 ----
  <para>
  See <filename>src/backend/storage/freespace/README</> for more details on
  how the <acronym>FSM</> is structured, and how it's updated and searched.
! The <link linkend="pgfreespacemap">pg_freespacemap</> module
! can be used to examine the information stored in free space maps.
  </para>

  </sect1>
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index b3e4b8e..d7e4fac 100644
*** /tmp/pgdiff.21665/HjSSKb_textsearch.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/1bZ00b_textsearch.sgml    Mon Jan 24 15:04:29 2011
*************** ALTER TEXT SEARCH CONFIGURATION astro_en
*** 2133,2140 ****
     normalize words to simplify the task of later dictionaries.  For example,
     a filtering dictionary could be used to remove accents from accented
     letters, as is done by the
!    <link linkend="unaccent"><filename>contrib/unaccent</></link>
!    extension module.
    </para>

    <sect2 id="textsearch-stopwords">
--- 2133,2140 ----
     normalize words to simplify the task of later dictionaries.  For example,
     a filtering dictionary could be used to remove accents from accented
     letters, as is done by the
!    <link linkend="unaccent">unaccent</link>
!    module.
    </para>

    <sect2 id="textsearch-stopwords">
*************** CREATE INDEX <replaceable>name</replacea
*** 3367,3374 ****
     allows the implementation of very fast searches with online update.
     Partitioning can be done at the database level using table inheritance,
     or by distributing documents over
!    servers and collecting search results using the <filename>contrib/dblink</>
!    extension module. The latter is possible because ranking functions use
     only local information.
    </para>

--- 3367,3374 ----
     allows the implementation of very fast searches with online update.
     Partitioning can be done at the database level using table inheritance,
     or by distributing documents over
!    servers and collecting search results using the <link linkend="dblink">dblink</>
!    module. The latter is possible because ranking functions use
     only local information.
    </para>

*************** Parser: "pg_catalog.default"
*** 3616,3623 ****
    <title>Migration from Pre-8.3 Text Search</title>

    <para>
!    Applications that used the <filename>contrib/tsearch2</> add-on module
!    for text searching will need some adjustments to work with the
     built-in features:
    </para>

--- 3616,3624 ----
    <title>Migration from Pre-8.3 Text Search</title>

    <para>
!    Applications that use the <link linkend="tsearch2">tsearch2</>
!    module for text searching will need some adjustments to work
!    with the
     built-in features:
    </para>

*************** Parser: "pg_catalog.default"
*** 3628,3634 ****
       argument lists, and all of them are now in the <literal>pg_catalog</>
       schema, whereas in a previous installation they would have been in
       <literal>public</> or another non-system schema.  There is a new
!      version of <filename>contrib/tsearch2</> (see <xref linkend="tsearch2">)
       that provides a compatibility layer to solve most problems in this
       area.
      </para>
--- 3629,3635 ----
       argument lists, and all of them are now in the <literal>pg_catalog</>
       schema, whereas in a previous installation they would have been in
       <literal>public</> or another non-system schema.  There is a new
!      version of <application>tsearch2</>
       that provides a compatibility layer to solve most problems in this
       area.
      </para>
*************** Parser: "pg_catalog.default"
*** 3636,3646 ****

     <listitem>
      <para>
!      The old <filename>contrib/tsearch2</> functions and other objects
       <emphasis>must</> be suppressed when loading <application>pg_dump</>
       output from a pre-8.3 database.  While many of them won't load anyway,
       a few will and then cause problems.  One simple way to deal with this
!      is to load the new <filename>contrib/tsearch2</> module before restoring
       the dump; then it will block the old objects from being loaded.
      </para>
     </listitem>
--- 3637,3647 ----

     <listitem>
      <para>
!      The old <application>tsearch2</> functions and other objects
       <emphasis>must</> be suppressed when loading <application>pg_dump</>
       output from a pre-8.3 database.  While many of them won't load anyway,
       a few will and then cause problems.  One simple way to deal with this
!      is to load the new <application>tsearch2</> module before restoring
       the dump; then it will block the old objects from being loaded.
      </para>
     </listitem>
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 38979cd..fa4cd32 100644
*** /tmp/pgdiff.21665/nHdbde_trigger.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/LrLBee_trigger.sgml    Mon Jan 24 15:04:29 2011
*************** DELETE 2
*** 832,838 ****
     <para>
      There are more complex examples in
      <filename>src/test/regress/regress.c</filename> and
!     in <filename>contrib/spi</filename>.
     </para>
    </sect1>
   </chapter>
--- 832,838 ----
     <para>
      There are more complex examples in
      <filename>src/test/regress/regress.c</filename> and
!     in <link linkend="spi">spi</>.
     </para>
    </sect1>
   </chapter>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index e7a5a91..5351eca 100644
*** /tmp/pgdiff.21665/tqjtkd_wal.sgml    Mon Jan 24 15:04:29 2011
--- /tmp/pgdiff.21665/1bDJfd_wal.sgml    Mon Jan 24 15:04:29 2011
***************
*** 129,136 ****
     file systems behave suboptimally when combined with battery-backup unit
     (<acronym>BBU</>) disk controllers.  In such setups, the synchronize
     command forces all data from the controller cache to the disks,
!    eliminating much of the benefit of the BBU.  You can run the utility
!    <filename>contrib/pg_test_fsync</> in the PostgreSQL source tree to see
     if you are affected.  If you are affected, the performance benefits
     of the BBU can be regained by turning off write barriers in
     the file system or reconfiguring the disk controller, if that is
--- 129,136 ----
     file systems behave suboptimally when combined with battery-backup unit
     (<acronym>BBU</>) disk controllers.  In such setups, the synchronize
     command forces all data from the controller cache to the disks,
!    eliminating much of the benefit of the BBU.  You can run the module
!    <link linkend="pgtestfsync">pg_test_fsync</> to see
     if you are affected.  If you are affected, the performance benefits
     of the BBU can be regained by turning off write barriers in
     the file system or reconfiguring the disk controller, if that is
***************
*** 571,578 ****
     the exception of <literal>fsync_writethrough</>, which can sometimes
     force a flush of the disk cache even when other options do not do so.
     However, it's quite platform-specific which one will be the fastest;
!    you can test option speeds using the utility <filename>contrib/pg_test_fsync</>
!    in the PostgreSQL source tree.
     Note that this parameter is irrelevant if <varname>fsync</varname>
     has been turned off.
    </para>
--- 571,578 ----
     the exception of <literal>fsync_writethrough</>, which can sometimes
     force a flush of the disk cache even when other options do not do so.
     However, it's quite platform-specific which one will be the fastest;
!    you can test option speeds using the module <link
!    linkend="pgtestfsync">pg_test_fsync</>.
     Note that this parameter is irrelevant if <varname>fsync</varname>
     has been turned off.
    </para>