From 3ddc548f4e6e62c553b29a754735526b4edd8a6c Mon Sep 17 00:00:00 2001
From: petere <petere>
Date: Wed, 4 Mar 2009 11:57:00 +0000
Subject: [PATCH] Provide some proper minimal documentation for the
 pg_dump(all) --binary-upgrade option.  We don't want to commit to what it
 does, but hiding it will only cause confusion.

---
 doc/src/sgml/ref/pg_dump.sgml    | 18 ++++++++++++------
 doc/src/sgml/ref/pg_dumpall.sgml | 18 ++++++++++++------
 src/bin/pg_dump/pg_dump.c        |  1 +
 src/bin/pg_dump/pg_dumpall.c     |  1 +
 4 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 04242c7030..b4b7ebb627 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -551,6 +551,18 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--binary-upgrade</option></term>
+      <listitem>
+       <para>
+        This option is for use by in-place upgrade utilities.  Its use
+        for other purposes is not recommended or supported.  The
+        behavior of the option may change in future releases without
+        notice.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>--disable-dollar-quoting</></term>
       <listitem>
        <para>
@@ -841,12 +853,6 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    that can be loaded into older database versions.  To do this, manual
    editing of the dump file might be required.
   </para>
-
-  <para>
-   <application>pg_dump</application> also supports a
-   <literal>--binary-upgrade</> option for upgrade utility usage.
-  </para>
-
  </refsect1>
 
  <refsect1 id="pg-dump-examples">
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 53d0be1b19..62d8dc6636 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -291,6 +291,18 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--binary-upgrade</option></term>
+      <listitem>
+       <para>
+        This option is for use by in-place upgrade utilities.  Its use
+        for other purposes is not recommended or supported.  The
+        behavior of the option may change in future releases without
+        notice.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>--disable-dollar-quoting</></term>
       <listitem>
        <para>
@@ -503,12 +515,6 @@ PostgreSQL documentation
    database creation will fail for databases in non-default
    locations.
   </para>
-
-  <para>
-   <application>pg_dump</application> also supports a
-   <literal>--binary-upgrade</> option for upgrade utility usage.
-  </para>
-
  </refsect1>
 
 
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index cbc54b9e95..99e5b88488 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -828,6 +828,7 @@ help(const char *progname)
 	printf(_("  -t, --table=TABLE           dump the named table(s) only\n"));
 	printf(_("  -T, --exclude-table=TABLE   do NOT dump the named table(s)\n"));
 	printf(_("  -x, --no-privileges         do not dump privileges (grant/revoke)\n"));
+	printf(_("  --binary-upgrade            for use by upgrade utilities only\n"));
 	printf(_("  --disable-dollar-quoting    disable dollar quoting, use SQL standard quoting\n"));
 	printf(_("  --disable-triggers          disable triggers during data-only restore\n"));
 	printf(_("  --no-tablespaces            do not dump tablespace assignments\n"));
diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c
index 2f8b2c3ac0..e3f26c69a3 100644
--- a/src/bin/pg_dump/pg_dumpall.c
+++ b/src/bin/pg_dump/pg_dumpall.c
@@ -521,6 +521,7 @@ help(void)
 	printf(_("  -S, --superuser=NAME        superuser user name to use in the dump\n"));
 	printf(_("  -t, --tablespaces-only      dump only tablespaces, no databases or roles\n"));
 	printf(_("  -x, --no-privileges         do not dump privileges (grant/revoke)\n"));
+	printf(_("  --binary-upgrade            for use by upgrade utilities only\n"));
 	printf(_("  --disable-dollar-quoting    disable dollar quoting, use SQL standard quoting\n"));
 	printf(_("  --disable-triggers          disable triggers during data-only restore\n"));
 	printf(_("  --no-tablespaces            do not dump tablespace assignments\n"));
-- 
2.11.4.GIT