From d537e0b41bbaa9c51f32bb07ffcc07bfdde8b3c5 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 13 Feb 2006 21:29:08 +0000
Subject: [PATCH] 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 | 10 ++++++----
 doc/src/sgml/ref/psql-ref.sgml   | 12 ++++++++----
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 21974eb619..e63c82ead2 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.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 52fb8fa141..b264216dff 100644
--- 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>