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.

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index fecce0a8457b6dda689da2575004b921495a4834..0ee4be87f099a5f1efd550cbdb020e934c5c3ea2 100644 (file)
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -1,10 +1,13 @@
-
- Standard Modules
+
+
+
+ Additional Supplied Modules
 
  
-  This section contains information regarding the standard modules which
+  This appendix contains information regarding the modules that
   can be found in the contrib directory of the
-  PostgreSQL distribution. These are porting tools, analysis utilities,
+  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 @@
  
 
  
-  Some modules supply new user-defined functions, operators, or types.  In 
-  these cases, you will need to run make and make
-  install in contrib/module. After you have 
-  installed the files you need to register the new entities in the database 
-  system by running the commands in the supplied .sql file.
-  For example,
-
-  
-   $ psql -d dbname -f module.sql
-  
-
-  You can modify the first command in the .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.
+  When building from the source distribution, these modules are not built
+  automatically.  You can build and install all of them by running
+
+gmake
+gmake install
+
+  in the contrib 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
+
+gmake installcheck
+
+  once you have a PostgreSQL server running.  (Note that
+  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.)
+ 
+
+ 
+  If you are using a pre-packaged version of PostgreSQL,
+  these modules are typically made available as a separate subpackage,
+  such as postgresql-contrib.
+ 
+
+ 
+  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 .sql file
+  supplied by the module.  For example,
+
+
+psql -d dbname -f SHAREDIR/contrib/module.sql
+
+
+  Here, SHAREDIR means the installation's share
+  directory (pg_config --sharedir will tell you what this is).
+ 
+
+ 
+  You need to run the .sql file in each database that you want
+  the module's facilities to be available in.  Alternatively, run it in
+  database template1 so that the module will be copied into
+  subsequently-created databases by default.
+ 
+
+ 
+  You can modify the first command in the .sql file to determine
+  which schema within the database the module's objects will be created in.
+  By default, they will be placed in public.
+ 
+
+ 
+  After a major-version upgrade of 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.
  
 
  &adminpack;
@@ -59,5 +107,5 @@
  &uuid-ossp;
  &vacuumlo;
  &xml2;
-
 
+

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2cc4d5731309113305297eb03daada7ad514f96c..3c3024e3f3c5e569f151901b15d7e8fb208ad81b 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,4 +1,4 @@
-
+
 
 
 
@@ -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;