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

don't promise more than the code actually delivers.

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 21974eb61925a3fd3ea0de8d778ab4c4b6981daa..e63c82ead2139e017852b9f5da53c5334b823b21 100644 (file)
--- 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.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>

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 52fb8fa141a0299cb37db7abb5463b83e4eac253..b264216dffe515f8fe1b1ca36acebc2f6d6892bf 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/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>