Add text to the VACUUM, REINDEX, DROP TABLESPACE and CREATE TABLESPACE

reference pages documenting that these commands cannot be used within
a transaction block. Also make some minor improvements to the psql
reference page. Patch from Simon Riggs, minor editorialization by
myself.

doc/src/sgml/ref/cluster.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.36 2006/09/16 00:30:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.37 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -60,8 +60,8 @@ CLUSTER
    in the
    current database that the calling user owns, or all tables if called
    by a superuser.  (Never-clustered tables are not included.)  This
-   form of <command>CLUSTER</command> cannot be called from inside a
+   form of <command>CLUSTER</command> cannot be executed inside a transaction
-   transaction or function.
+   block.
   </para>
 
   <para>

doc/src/sgml/ref/create_tablespace.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_tablespace.sgml,v 1.6 2006/09/16 00:30:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_tablespace.sgml,v 1.7 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -95,6 +95,11 @@ CREATE TABLESPACE <replaceable class="parameter">tablespacename</replaceable> [
   <para>
    Tablespaces are only supported on systems that support symbolic links.
   </para>
+
+   <para>
+    <command>CREATE TABLESPACE</> cannot be executed inside a transaction
+    block.
+   </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/drop_tablespace.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_tablespace.sgml,v 1.4 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_tablespace.sgml,v 1.5 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -66,6 +66,15 @@ DROP TABLESPACE [ IF EXISTS ] <replaceable class="PARAMETER">tablespacename</rep
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+   <para>
+    <command>DROP TABLESPACE</> cannot be executed inside a transaction block.
+   </para>
+ </refsect1>
+
+
  <refsect1>
   <title>Examples</title>
 

doc/src/sgml/ref/psql-ref.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.172 2006/10/23 18:10:32 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.173 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -94,9 +94,10 @@ PostgreSQL documentation
       <para>
        If the command string contains multiple SQL commands, they are
        processed in a single transaction, unless there are explicit
-       BEGIN/COMMIT commands included in the string to divide it into
+       <command>BEGIN</>/<command>COMMIT</> commands included in the
-       multiple transactions.  This is different from the behavior when
+       string to divide it into multiple transactions.  This is
-       the same string is fed to <application>psql</application>'s standard input.
+       different from the behavior when the same string is fed to
+       <application>psql</application>'s standard input.
       </para>
       </listitem>
     </varlistentry>
@@ -472,9 +473,14 @@ PostgreSQL documentation
         <option>-f</> option, adding this option wraps
         <command>BEGIN</>/<command>COMMIT</> around the script to execute it
         as a single transaction.  This ensures that either all the commands
-        complete successfully, or no changes are applied.  (However, if the
+        complete successfully, or no changes are applied.  
-        script itself uses <command>BEGIN</> or <command>COMMIT</>, this
+       </para>
-        option will not have the desired effect!)
+
+       <para>
+        If the script itself uses <command>BEGIN</>, <command>COMMIT</>
+        or any command that cannot be executed inside a transaction
+        block, specifying this option will cause the transaction to be
+        aborted.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/reindex.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/reindex.sgml,v 1.33 2006/09/16 00:30:19 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/reindex.sgml,v 1.34 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -106,7 +106,8 @@ REINDEX { INDEX | TABLE | DATABASE | SYSTEM } <replaceable class="PARAMETER">nam
      <para>
       Recreate all indexes within the current database.
       Indexes on shared system catalogs are skipped except in stand-alone mode
-      (see below).
+      (see below). This form of <command>REINDEX</command> cannot be executed 
+      inside a transaction block.
      </para>
     </listitem>
    </varlistentry>
@@ -118,6 +119,8 @@ REINDEX { INDEX | TABLE | DATABASE | SYSTEM } <replaceable class="PARAMETER">nam
       Recreate all indexes on system catalogs within the current database.
       Indexes on user tables are not processed.  Also, indexes on shared
       system catalogs are skipped except in stand-alone mode (see below).
+      This form of <command>REINDEX</command> cannot be executed inside a
+      transaction block.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/vacuum.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.41 2006/09/16 00:30:20 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.42 2006/10/31 01:52:31 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -155,6 +155,10 @@ VACUUM [ FULL | FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">ta
  <refsect1>
   <title>Notes</title>
 
+   <para>
+    <command>VACUUM</> cannot be executed inside a transaction block.
+   </para>
+
    <para>
     We recommend that active production databases be
     vacuumed frequently (at least nightly), in order to