Various fixes for the SGML docs. Consistently use spaces before/after

parentheses in syntax descriptions. Consistently use the present tense
when describing the basic purpose of each "DROP" command. Add a few
more hyperlinks.

15 files changed, 49 insertions, 47 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 2da4abc3407..1bf95871c0e 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.151 2007/05/11 17:57:11 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.152 2007/05/15 19:13:54 neilc Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -3984,12 +3984,13 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_statistic</structname> stores statistical data
-   about the contents of the database.  Entries are created by
-   <command>ANALYZE</command> and subsequently used by the query planner.
-   There is one entry for each table column that has been analyzed.
-   Note that all the statistical data is inherently approximate,
-   even assuming that it is up-to-date.
+   The catalog <structname>pg_statistic</structname> stores
+   statistical data about the contents of the database.  Entries are
+   created by <xref linkend="sql-analyze" endterm="sql-analyze-title">
+   and subsequently used by the query planner.  There is one entry for
+   each table column that has been analyzed.  Note that all the
+   statistical data is inherently approximate, even assuming that it
+   is up-to-date.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml
index 813235fd602..93273c11d81 100644
--- a/doc/src/sgml/ref/alter_index.sgml
+++ b/doc/src/sgml/ref/alter_index.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_index.sgml,v 1.12 2007/01/31 23:26:02 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_index.sgml,v 1.13 2007/05/15 19:13:54 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -109,7 +109,7 @@ ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RESET ( <replaceab
       <term><replaceable class="PARAMETER">new_name</replaceable></term>
       <listitem>
        <para>
-        New name for the index.
+        The new name for the index.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 28c272179aa..bb293af03cc 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.21 2007/01/31 23:26:02 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.22 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
+ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -29,10 +29,11 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
 
   <para>
    <command>ANALYZE</command> collects statistics about the contents
-   of tables in the database, and stores the results in the system
-   table <literal>pg_statistic</literal>.  Subsequently, the query
-   planner uses these statistics to help determine the most efficient
-   execution plans for queries.
+   of tables in the database, and stores the results in the <link
+   linkend="catalog-pg-statistic"><structname>pg_statistic</></>
+   system catalog.  Subsequently, the query planner uses these
+   statistics to help determine the most efficient execution plans for
+   queries.
   </para>
 
   <para>
@@ -125,7 +126,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
    will change slightly each time <command>ANALYZE</command> is run,
    even if the actual table contents did not change.  This might result
    in small changes in the planner's estimated costs shown by
-   <command>EXPLAIN</command>. In rare situations, this
+   <xref linkend="sql-explain" endterm="sql-explain-title">. In rare situations, this
    non-determinism will cause the query optimizer to choose a
    different query plan between runs of <command>ANALYZE</command>. To
    avoid this, raise the amount of statistics collected by
diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml
index 2e5309ff0f2..f4fada4ac71 100644
--- a/doc/src/sgml/ref/close.sgml
+++ b/doc/src/sgml/ref/close.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.25 2007/04/12 06:53:45 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.26 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -88,8 +88,8 @@ CLOSE { <replaceable class="PARAMETER">name</replaceable> | ALL }
   </para>
 
   <para>
-   You can see all available cursors by querying the
-   <structname>pg_cursors</structname> system view.
+   You can see all available cursors by querying the <link
+   linkend="view-pg-cursors"><structname>pg_cursors</></> system view.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml
index ebb1466bc08..d73f14b2d87 100644
--- a/doc/src/sgml/ref/drop_aggregate.sgml
+++ b/doc/src/sgml/ref/drop_aggregate.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.30 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.31 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -28,7 +28,7 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> (
   <title>Description</title>
 
   <para>
-   <command>DROP AGGREGATE</command> will delete an existing
+   <command>DROP AGGREGATE</command> removes an existing
    aggregate function. To execute this command the current
    user must be the owner of the aggregate function.
   </para>
diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml
index ebb7eb500b7..2e7f9e37cd7 100644
--- a/doc/src/sgml/ref/drop_domain.sgml
+++ b/doc/src/sgml/ref/drop_domain.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.17 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.18 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-DROP DOMAIN [IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...]  [ CASCADE | RESTRICT ]
+DROP DOMAIN [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -28,8 +28,8 @@ DROP DOMAIN [IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ..
   <title>Description</title>
 
   <para>
-   <command>DROP DOMAIN</command> will remove a domain.  Only the
-   owner of a domain can remove it.
+   <command>DROP DOMAIN</command> removes a domain.  Only the owner of
+   a domain can remove it.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml
index 1e3c960a720..ca0d667b6eb 100644
--- a/doc/src/sgml/ref/drop_language.sgml
+++ b/doc/src/sgml/ref/drop_language.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_language.sgml,v 1.25 2007/03/26 16:58:38 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_language.sgml,v 1.26 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -28,11 +28,9 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <replaceable class="PARAMETER">name</
   <title>Description</title>
 
   <para>
-   <command>DROP LANGUAGE</command> will remove the definition
-   of the previously registered procedural language called
-   <replaceable class="parameter">name</replaceable>.
-   You must be superuser or owner of the language to
-   use <command>DROP LANGUAGE</command>.
+   <command>DROP LANGUAGE</command> removes the definition of a
+   previously registered procedural language.  You must be a superuser
+   or the owner of the language to use <command>DROP LANGUAGE</>.
   </para>
  </refsect1>
   
diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml
index b0755ee1889..58be47acb07 100644
--- a/doc/src/sgml/ref/drop_sequence.sgml
+++ b/doc/src/sgml/ref/drop_sequence.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.26 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.27 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -28,7 +28,8 @@ DROP SEQUENCE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [,
   <title>Description</title>
 
   <para>
-   <command>DROP SEQUENCE</command> removes sequence number generators.
+   <command>DROP SEQUENCE</command> removes sequence number
+   generators. A sequence can only be dropped by its owner or a superuser.
   </para>
  </refsect1>
   
diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml
index 46ee3ac9b09..287d6dbd997 100644
--- a/doc/src/sgml/ref/drop_table.sgml
+++ b/doc/src/sgml/ref/drop_table.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.26 2007/01/31 23:26:03 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.27 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -29,7 +29,7 @@ DROP TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ..
 
   <para>
    <command>DROP TABLE</command> removes tables from the database.
-   Only its owner can destroy a table.  To empty a table of rows
+   Only its owner can drop a table.  To empty a table of rows
    without destroying the table, use <xref linkend="sql-delete"
    endterm="sql-delete-title"> or <xref linkend="sql-truncate"
    endterm="sql-truncate-title">.
diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml
index a579d5794d6..9b7103a926c 100644
--- a/doc/src/sgml/ref/drop_trigger.sgml
+++ b/doc/src/sgml/ref/drop_trigger.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_trigger.sgml,v 1.21 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_trigger.sgml,v 1.22 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -28,7 +28,7 @@ DROP TRIGGER [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> ON
   <title>Description</title>
 
   <para>
-   <command>DROP TRIGGER</command> will remove an existing
+   <command>DROP TRIGGER</command> removes an existing
    trigger definition. To execute this command, the current
    user must be the owner of the table for which the trigger is defined.
   </para>
diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml
index 139690879f6..43884331876 100644
--- a/doc/src/sgml/ref/drop_type.sgml
+++ b/doc/src/sgml/ref/drop_type.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.29 2006/10/23 18:10:32 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.30 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -28,7 +28,7 @@ DROP TYPE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...
   <title>Description</title>
 
   <para>
-   <command>DROP TYPE</command> will remove a user-defined data type.
+   <command>DROP TYPE</command> removes a user-defined data type.
    Only the owner of a type can remove it.
   </para>
  </refsect1>
diff --git a/doc/src/sgml/ref/execute.sgml b/doc/src/sgml/ref/execute.sgml
index be3ba28a799..cc95860915a 100644
--- a/doc/src/sgml/ref/execute.sgml
+++ b/doc/src/sgml/ref/execute.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/execute.sgml,v 1.14 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/execute.sgml,v 1.15 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -25,7 +25,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-EXECUTE <replaceable class="PARAMETER">name</replaceable> [ (<replaceable class="PARAMETER">parameter</replaceable> [, ...] ) ]
+EXECUTE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class="PARAMETER">parameter</replaceable> [, ...] ) ]
 </synopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 8ed0a57b58e..a311affc3c3 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.70 2007/03/26 17:23:37 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.71 2007/05/15 19:13:55 neilc Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -11,7 +11,8 @@
   <refname>pg_restore</refname>
 
   <refpurpose>
-   restore a <productname>PostgreSQL</productname> database from an archive file created by pg_dump
+   restore a <productname>PostgreSQL</productname> database from an
+   archive file created by <application>pg_dump</application>
   </refpurpose>
  </refnamediv>
 
diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml
index 62097152beb..c7be790b71f 100644
--- a/doc/src/sgml/ref/prepare.sgml
+++ b/doc/src/sgml/ref/prepare.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.22 2007/01/31 23:26:04 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.23 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -25,7 +25,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-PREPARE <replaceable class="PARAMETER">name</replaceable> [ (<replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">statement</replaceable>
+PREPARE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">statement</replaceable>
 </synopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 689a4985665..0f1ada97cb6 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.99 2007/02/01 19:10:25 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.100 2007/05/15 19:13:55 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -354,7 +354,7 @@ where <replaceable class="parameter">from_item</replaceable> can be one of:
      </varlistentry>
      
      <varlistentry>
-      <term><literal>USING (<replaceable class="parameter">join_column</replaceable> [, ...])</literal></term>
+      <term><literal>USING ( <replaceable class="parameter">join_column</replaceable> [, ...] )</literal></term>
       <listitem>
        <para>
         A clause of the form <literal>USING ( a, b, ... )</literal> is