From f2727f542fca3970d995877cdbca7c6cf040a492 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 20 May 2016 14:59:48 -0400
Subject: [PATCH] Improve documentation about pg_dump's --quote-all-identifiers
 switch.
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Per bug #14152 from Alejandro Martínez.  Back-patch to all supported
branches.

Discussion: <20160520165824.22598.31426@wrigleys.postgresql.org>
---
 doc/src/sgml/ref/pg_dump.sgml    | 13 ++++++++++---
 doc/src/sgml/ref/pg_dumpall.sgml | 13 ++++++++++---
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index eaeb9a787ef..2c2a5cf8328 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -792,9 +792,16 @@ PostgreSQL documentation
       <term><option>--quote-all-identifiers</></term>
       <listitem>
        <para>
-        Force quoting of all identifiers.  This may be useful when dumping a
-        database for migration to a future version that may have introduced
-        additional keywords.
+        Force quoting of all identifiers.  This option is recommended when
+        dumping a database from a server whose <productname>PostgreSQL</>
+        major version is different from <application>pg_dump</>'s, or when
+        the output is intended to be loaded into a server of a different
+        major version.  By default, <application>pg_dump</> quotes only
+        identifiers that are reserved words in its own major version.
+        This sometimes results in compatibility issues when dealing with
+        servers of other versions that may have slightly different sets
+        of reserved words.  Using <option>--quote-all-identifiers</> prevents
+        such issues, at the price of a harder-to-read dump script.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 5c6a101333f..f7036407973 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -367,9 +367,16 @@ PostgreSQL documentation
       <term><option>--quote-all-identifiers</></term>
       <listitem>
        <para>
-        Force quoting of all identifiers.  This may be useful when dumping a
-        database for migration to a future version that may have introduced
-        additional keywords.
+        Force quoting of all identifiers.  This option is recommended when
+        dumping a database from a server whose <productname>PostgreSQL</>
+        major version is different from <application>pg_dumpall</>'s, or when
+        the output is intended to be loaded into a server of a different
+        major version.  By default, <application>pg_dumpall</> quotes only
+        identifiers that are reserved words in its own major version.
+        This sometimes results in compatibility issues when dealing with
+        servers of other versions that may have slightly different sets
+        of reserved words.  Using <option>--quote-all-identifiers</> prevents
+        such issues, at the price of a harder-to-read dump script.
        </para>
       </listitem>
      </varlistentry>
-- 
2.39.5