Improve documentation of pg_restore's -l and -L switches to point out their

interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 0302418cefc6f6b0b3050614faae81ac9e0df84b..70a8b41ee6c77c8532b926e462f9087d9bffaaae 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  
@@ -47,10 +47,11 @@
 
   
    pg_restore can operate in two modes.
-   If a database name is specified, the archive is restored directly into
+   If a database name is specified, pg_restore
+   connects to that database and restores archive contents directly into
    the database.  Otherwise, a script containing the SQL
    commands necessary to rebuild the database is created and written
-   to a file or standard output.  The script output is equivalent to
+   to a file or standard output.  This script output is equivalent to
    the plain text output format of pg_dump.
    Some of the options controlling the output are therefore analogous to
    pg_dump options.
@@ -170,10 +171,7 @@
          tar
          
           
-           The archive is a tar archive. Using this
-           archive format allows reordering and/or exclusion of schema
-           elements at the time the database is restored. It is also
-           possible to limit which data is reloaded at restore time.
+           The archive is a tar archive.
           
          
         
@@ -184,10 +182,7 @@
          
           
            The archive is in the custom format of
-           pg_dump. This is the most
-           flexible format in that it allows reordering of data load
-           as well as schema elements.  This format is also compressed
-           by default.
+           pg_dump.
           
          
         
@@ -262,8 +257,9 @@
       
        
         List the contents of the archive. The output of this operation
-        can be used with the -L option to restrict
-        and reorder the items that are restored.
+        can be used as input to the -L option.  Note that
+        if filtering switches such as -n or -t are
+        used with -l, they will restrict the items listed.
        
       
      
@@ -273,11 +269,18 @@
       --use-list=list-file
       
        
-        Restore elements in 
-        list-file only, and in the
-        order they appear in the file. Lines can be moved and can also
-        be commented out by placing a ; at the
-        start of the line.  (See below for examples.)
+        Restore only those archive elements that are listed in 
+        class="PARAMETER">list-file, and restore them in the
+        order they appear in the file.  Note that
+        if filtering switches such as -n or -t are
+        used with -L, they will further restrict the items restored.
+       
+       
+        list-file is normally created by
+        editing the output of a previous -l operation.
+        Lines can be moved or removed, and can also
+        be commented out by placing a semicolon (;) at the
+        start of the line.  See below for examples.