Move contrib docs to an appendix (next door to External Projects).

Change title to Additional Supplied Modules.  Improve discussion of
how to build and install 'em.

doc/src/sgml/contrib.sgml

@@ -1,10 +1,13 @@
-<chapter id="contrib">
- <title>Standard Modules</title>
+<!-- $PostgreSQL: pgsql/doc/src/sgml/contrib.sgml,v 1.4 2007/11/14 02:36:43 tgl Exp $ -->
+
+<appendix id="contrib">
+ <title>Additional Supplied Modules</title>
 
  <para>
-  This section contains information regarding the standard modules which
+  This appendix contains information regarding the modules that
   can be found in the <literal>contrib</literal> directory of the
-  PostgreSQL distribution. These are porting tools, analysis utilities,
+  <productname>PostgreSQL</> distribution.
+  These include porting tools, analysis utilities,
   and plug-in features that are not part of the core PostgreSQL system,
   mainly because they address a limited audience or are too experimental
   to be part of the main source tree.  This does not preclude their
@@ -12,21 +15,66 @@
  </para>
 
  <para>
-  Some modules supply new user-defined functions, operators, or types.  In 
-  these cases, you will need to run <literal>make</literal> and <literal>make
-  install</literal> in <literal>contrib/module</literal>. After you have 
-  installed the files you need to register the new entities in the database 
-  system by running the commands in the supplied <literal>.sql</> file.
-  For example,
+  When building from the source distribution, these modules are not built
+  automatically.  You can build and install all of them by running
+<screen>
+<userinput>gmake</userinput>
+<userinput>gmake install</userinput>
+</screen>
+  in the <literal>contrib</literal> directory of a configured source tree;
+  or to build and install
+  just one selected module, do the same in that module's subdirectory.
+  Many of the modules have regression tests, which can be executed by
+  running
+<screen>
+<userinput>gmake installcheck</userinput>
+</screen>
+  once you have a <productname>PostgreSQL</> server running.  (Note that
+  <literal>gmake check</> is not supported; you must have an operational
+  database server to perform these tests, and you must have built and
+  installed the module(s) to be tested.)
+ </para>
 
-  <programlisting>
-   $ psql -d dbname -f module.sql
-  </programlisting>
+ <para>
+  If you are using a pre-packaged version of <productname>PostgreSQL</>,
+  these modules are typically made available as a separate subpackage,
+  such as <literal>postgresql-contrib</>.
+ </para>
 
-  You can modify the first command in the <literal>.sql</> file to control
-  the schema where the module is created.  During major upgrades, even
-  though the restored database might already have the desired module
-  functions, run the installation script again to add any new functions.
+ <para>
+  Many modules supply new user-defined functions, operators, or types.
+  To make use of one of these modules, after you have installed the code
+  you need to register the new objects in the database 
+  system by running the SQL commands in the <literal>.sql</> file
+  supplied by the module.  For example,
+
+<programlisting>
+psql -d dbname -f <replaceable>SHAREDIR</>/contrib/<replaceable>module</>.sql
+</programlisting>
+
+  Here, <replaceable>SHAREDIR</> means the installation's <quote>share</>
+  directory (<literal>pg_config --sharedir</> will tell you what this is).
+ </para>
+
+ <para>
+  You need to run the <literal>.sql</> file in each database that you want
+  the module's facilities to be available in.  Alternatively, run it in
+  database <literal>template1</> so that the module will be copied into
+  subsequently-created databases by default.
+ </para>
+
+ <para>
+  You can modify the first command in the <literal>.sql</> file to determine
+  which schema within the database the module's objects will be created in.
+  By default, they will be placed in <literal>public</>.
+ </para>
+
+ <para>
+  After a major-version upgrade of <productname>PostgreSQL</>, run the
+  installation script again, even though the module's objects might have
+  been brought forward from the old installation by dump and restore.
+  This ensures that any new functions will be available and any needed
+  corrections will be applied.
  </para>
 
  &adminpack;
@@ -59,5 +107,5 @@
  &uuid-ossp;
  &vacuumlo;
  &xml2;
-</chapter>
 
+</appendix>

doc/src/sgml/postgres.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.84 2007/11/10 23:30:46 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.85 2007/11/14 02:36:43 tgl Exp $ -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
 
@@ -102,7 +102,6 @@
   &typeconv;
   &indices;
   &textsearch;
-  &contrib;
   &mvcc;
   &perform;
 
@@ -254,9 +253,10 @@
   &keywords;
   &features;
   &release;
+  &contrib;
+  &external-projects;
   &cvs;
   &docguide;
-  &external-projects;
   &acronyms;
 
  </part>