Update extensions/README (#1720)

- reStructuredText Markup, 80 column text
- Rewrite several paragraphs
- Add requirements section
- Make it clear that --with-raster is required, and that postgis also
  includes the raster support

Patch by Mike Toews

git-svn-id: http://svn.osgeo.org/postgis/trunk@9555 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/extensions/README b/extensions/README
index 1d5fbd445854afbc473e2b1fe86c8f31dfc95988..935f2b74094a4ea8bc76867c3daeeb6c060212d6 100644 (file)
--- a/extensions/README
+++ b/extensions/README
@@ -1,42 +1,64 @@
-These are extension modules for PostgreQL 9.1
-to allow postgis modules
-to be installed using standard PostgreSQL 9.1+
-CREATE EXTENSION syntax
+PostGIS Extension for PostgreSQL
+================================
 
-To use: first make install regular PostGIS.  Also make sure to make the comments
-if you are building from teh source repository
-since the extensions package the postgis function descriptions.
-make comments
+PostgreSQL 9.1 (and up) supports PostGIS extensions. A database can easily be
+extended to use PostGIS using the syntax::
 
-Makign the comments is not necessary if you are building 
-from the tar balls since the tar balls have 
-the various postgis_comments.sql, topology_comments.sql, 
-and raster_comments.sql already built.
+  CREATE EXTENSION postgis;           -- Includes raster
+  CREATE EXTENSION postgis_topology;  -- Depends on postgis
 
-Then:
-cd extensions/postgis
-make install
-cd ..
-cd extensions/postgis_topology
-make install
+Requirements
+------------
+ * PostgreSQL 9.1 or later
+ * PostGIS must be configured and built ``--with-raster``
 
-These should automatically get installed in share/extension folder of
-PostgreSQL 9.1.
+Building and installing
+-----------------------
+First, make sure you follow the regular configuration and installation steps,
+completing these steps::
 
-Then in your PostgreSQL database run
-CREATE EXTENSION postgis;
-CREATE EXTENSION postgis_topology;
+  make
+  make install
 
+If you are building from the source SVN repository, it is also recommended to
+make the comments, since the function descriptions will be included::
 
-The dependency logic should warn if you try
-to install postgis_topology without postgis
-or try to drop postgis without first droping postgis_topology.
+  make comments
 
-You will also not be able to drop any postgis functions installed by the extension.
-If you want to manually install the extensions from one server to another
-, just copy over the
+Making the comments is not necessary if you are building from the tar.gz source
+distributions, since these include pre-built ``postgis_comments.sql``,
+``topology_comments.sql``, and ``raster_comments.sql`` files.
 
-extensions/postgis: postgis.control, sql/*
-extension/postgis_topoloyg postgis_topology.control,sql/* 
+Then, to build and install the extensions::
 
-files into your PostgreSQL/share/extension folder.
\ No newline at end of file
+  cd extensions
+  make
+  make install
+
+The extensions are installed in `SHAREDIR/extension`. (If you're uncertain
+where `SHAREDIR` is, run ``pg_config --sharedir``.)
+
+Then in your PostgreSQL database run::
+
+  CREATE EXTENSION postgis;
+  CREATE EXTENSION postgis_topology;
+
+The dependency logic should warn if you try to install ``postgis_topology``
+without ``postgis`` or try to drop ``postgis`` without first dropping
+``postgis_topology``.
+
+You will also not be able to drop any PostGIS functions installed by the
+extension.
+
+Manual extension installation
+-----------------------------
+If you want to manually install the extensions from one server to another,
+just copy over the following files to the `SHAREDIR/extension` directory:
+
+ * PostGIS (including raster); from ``extensions/postgis``:
+    ``postgis.control``
+    ``sql/*``
+
+ * Topology extension; from ``extensions/postgis_topolology``:
+     ``postgis_topology.control``
+     ``sql/*``