Improve documentation of --single-transaction option: fix markup, and

don't promise more than the code actually delivers.

doc/src/sgml/ref/pg_restore.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.57 2006/02/12 04:04:32 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.58 2006/02/13 21:29:08 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -454,9 +454,11 @@
       <term><option>--single-transaction</option></term>
       <listitem>
        <para>
-        Force the restore to execute as a single transaction. Either all
-        SQL statements complete successfully, or no changes are applied. This
-        option also forces --exit-on-error.
+        Execute the restore as a single transaction (that is, wrap the
+        emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
+        ensures that either all the commands complete successfully, or no
+        changes are applied. This option implies
+        <option>--exit-on-error</>.
        </para>
       </listitem>
      </varlistentry>

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

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.159 2006/02/12 04:04:32 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.160 2006/02/13 21:29:08 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -468,9 +468,13 @@ PostgreSQL documentation
       <term><option>--single-transaction</option></term>
       <listitem>
        <para>
-        When psql executes a script with the -f option, this additional option
-        will force the script to execute as a single transaction. Either all
-        SQL statements complete successfully, or no changes are applied. 
+        When <application>psql</application> executes a script with the
+        <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
+        script itself uses <command>BEGIN</> or <command>COMMIT</>, this
+        option will not have the desired effect!)
        </para>
       </listitem>
      </varlistentry>