Make documentation of pg_restore's -N, -o, -r switches bear some

slight resemblance to their actual behavior.

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index cf028b93e59237b2df9a10c48bed3bebeb6f36c0..e342327e74f3c888b5952e5a60b8d55f01a807e3 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  
@@ -42,8 +42,8 @@
   
    pg_restore can operate in two modes: If
    a database name is specified, the archive is restored directly into
-   the database.  Large objects can only be restored by using a direct
-   database connection.  Otherwise, a script containing the SQL
+   the database.  (Large objects can only be restored by using such a direct
+   database connection.)  Otherwise, a script containing the SQL
    commands necessary to rebuild the database is created (and written
    to a file or standard output), similar to the ones created by the
    pg_dump plain text format.  Some of the
@@ -228,11 +228,13 @@
       --orig-order
       
        
-        Restore items in the original dump order. By default
-        pg_dump will dump items in an order
-        convenient to pg_dump, then save the
-        archive in a modified OID order. This option overrides the OID
-        ordering.
+        Restore items in the order they were originally generated within
+        pg_dump.  This option has no known
+   practical use, since pg_dump generates
+   the items in an order convenient to it, which is unlikely to be a
+   safe order for restoring them.  (This is not the order
+   in which the items are ultimately listed in the archive's table of
+   contents.)  See also -r.
        
       
      
@@ -242,11 +244,10 @@
       --oid-order
       
        
-        Restore items in the OID order. By default
-        pg_dump will dump items in an order
-        convenient to pg_dump, then save the
-        archive in a modified OID order. This option enforces strict
-        OID ordering.
+        Restore items in order by OID.  This option is of limited usefulness,
+   since OID is only an approximate indication of original creation
+   order.  This option overrides -N if both are specified.
+   See also -r.
        
       
      
@@ -281,13 +282,22 @@
       --rearrange
       
        
-        Restore items in modified OID order. By default
-        pg_dump will dump items in an order
-        convenient to pg_dump, then save the
-        archive in a modified OID order. Most objects will be restored
-        in OID order, but some things (e.g., rules and indexes) will
-        be restored at the end of the process irrespective of their
-        OIDs. This option is the default.
+        Rearrange items by object type (this occurs after the sorting
+   specified by -N or -o, if
+   given).  The rearrangement is intended to give the best possible
+   restore performance.
+       
+
+       
+        When none of -N, -o, and
+   -r appear, pg_restore restores
+   items in the order they appear in the dump's table of contents,
+   or in the order they appear in the  
+        CLASS="PARAMETER">list-file if -L is
+   given.  The combination of -o and -r
+   duplicates the sorting done by pg_dump
+   before creating the dump's table of contents,
+   and so it is normally unnecessary to specify it.