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.

doc/src/sgml/ref/pg_restore.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64.2.2 2007/03/26 17:23:45 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64.2.3 2010/05/15 18:11:25 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -45,10 +45,11 @@
 
   <para>
    <application>pg_restore</application> can operate in two modes.
-   If a database name is specified, the archive is restored directly into
+   If a database name is specified, <application>pg_restore</application>
+   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 <application>pg_dump</application>.
    Some of the options controlling the output are therefore analogous to
    <application>pg_dump</application> options.
@@ -168,10 +169,7 @@
          <term><literal>tar</></term>
          <listitem>
           <para>
-           The archive is a <command>tar</command> archive. Using this
+           The archive is a <command>tar</command> archive.
-           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.
           </para>
          </listitem>
         </varlistentry>
@@ -182,10 +180,7 @@
          <listitem>
           <para>
            The archive is in the custom format of
-           <application>pg_dump</application>. This is the most
+           <application>pg_dump</application>.
-           flexible format in that it allows reordering of data load
-           as well as schema elements.  This format is also compressed
-           by default.
           </para>
          </listitem>
         </varlistentry>
@@ -220,8 +215,9 @@
       <listitem>
        <para>
         List the contents of the archive. The output of this operation
-        can be used with the <option>-L</option> option to restrict
+        can be used as input to the <option>-L</option> option.  Note that
-        and reorder the items that are restored.
+        if filtering switches such as <option>-n</> or <option>-t</> are
+        used with <option>-l</>, they will restrict the items listed.
        </para>
       </listitem>
      </varlistentry>
@@ -231,11 +227,18 @@
       <term><option>--use-list=<replaceable class="parameter">list-file</replaceable></option></term>
       <listitem>
        <para>
-        Restore elements in <replaceable class="PARAMETER">
+        Restore only those archive elements that are listed in <replaceable
-        list-file</replaceable> only, and in the
+        class="PARAMETER">list-file</replaceable>, and restore them in the
-        order they appear in the file. Lines can be moved and may also
+        order they appear in the file.  Note that
-        be commented out by placing a <literal>;</literal> at the
+        if filtering switches such as <option>-n</> or <option>-t</> are
-        start of the line.  (See below for examples.)
+        used with <option>-L</>, they will further restrict the items restored.
+       </para>
+       <para>
+        <replaceable class="PARAMETER">list-file</> is normally created by
+        editing the output of a previous <option>-l</> operation.
+        Lines can be moved or removed, and can also
+        be commented out by placing a semicolon (<literal>;</literal>) at the
+        start of the line.  See below for examples.
        </para>
       </listitem>
      </varlistentry>