Re: pg_upgrade docs

Bruce Momjian wrote:
> I have created the attached patch which rewords the mention of
> pg_upgrade in the docs.  I think it is clearer and more concise.  Should
> we mention that people should have a recent pg_dump?  If so, that should
> be in the pg_upgrade man page, not here.

Applied attached patch that mentions pg_upgrade in a less risk-warning
way, and incorporate Robert Haas's ideas (mention storage format
changes) into pg_upgrade docs.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml
index c167cd9..261177c 100644
*** a/doc/src/sgml/pgupgrade.sgml
--- b/doc/src/sgml/pgupgrade.sgml
***************
*** 17,25 ****
   </para>

   <para>
!   <application>pg_upgrade</> works because, though new features are
!   regularly added to PostgreSQL major releases, the internal data storage
!   format rarely changes.  <application>pg_upgrade</> does its best to
    make sure the old and new clusters are binary-compatible, e.g.  by
    checking for compatible compile-time settings, including 32/64-bit
    binaries.  It is important that
--- 17,35 ----
   </para>

   <para>
!   Major PostgreSQL releases regularly add new features that often
!   change the layout of the system tables, but the internal data storage
!   format rarely changes.  <application>pg_upgrade</> uses this fact
!   to perform rapid upgrades by creating new system tables and simply
!   reusing the old user data files.  If a future major release ever
!   changes the data storage format in a way that makes the old data
!   format unreadable, <application>pg_upgrade</> will not be usable
!   for such upgrades.  (The community will attempt to avoid such
!   situations.)
!  </para>
!
!  <para>
!   <application>pg_upgrade</> does its best to
    make sure the old and new clusters are binary-compatible, e.g.  by
    checking for compatible compile-time settings, including 32/64-bit
    binaries.  It is important that
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 504881d..4f59fd1 100644
*** a/doc/src/sgml/runtime.sgml
--- b/doc/src/sgml/runtime.sgml
*************** pg_dumpall -p 5432 | psql -d postgres -p
*** 1692,1708 ****
    </sect2>

    <sect2 id="upgrading-methods-other">
!    <title>Other data migration methods</title>

     <para>
!     The <filename>contrib</> program
!     <link linkend="pgupgrade"><application>pg_upgrade</application></link>
!     allows an installation to be migrated in-place from one major
!     <productname>PostgreSQL</> version to the next.  Keep in mind that this
!     method does not provide any scope for running old and new versions
!     concurrently.  Also, <application>pg_upgrade</application> is much less
!     battle-tested than <application>pg_dump</application>, so having an
!     up-to-date backup is strongly recommended in case something goes wrong.
     </para>

     <para>
--- 1692,1704 ----
    </sect2>

    <sect2 id="upgrading-methods-other">
!    <title>Non-Dump Upgrade Methods</title>

     <para>
!     The <link linkend="pgupgrade">pg_upgrade</link> module allows an
!     installation to be migrated in-place from one major
!     <productname>PostgreSQL</> version to the next.  Upgrades can be
!     performed in minutes.
     </para>

     <para>