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

tglsfdc · tglsfdc · commit 8be5f6ecaa60 · 2010-05-15T18:11:35.000Z
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
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49.4.1 2005/01/23 00:37:56 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49.4.2 2010/05/15 18:11:35 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -168,10 +168,7 @@
          <term><literal>t</></term>
          <listitem>
           <para>
-           The archive is a <command>tar</command> 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 <command>tar</command> archive.
           </para>
          </listitem>
         </varlistentry>
@@ -181,10 +178,7 @@
          <listitem>
           <para>
            The archive is in the custom format of
-           <application>pg_dump</application>. 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.
+           <application>pg_dump</application>.
           </para>
          </listitem>
         </varlistentry>
@@ -219,8 +213,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
-        and reorder the items that are restored.
+        can be used as input to the <option>-L</option> option.  Note that
+        if filtering switches such as <option>-n</> or <option>-t</> are
+        used with <option>-l</>, they will restrict the items listed.
        </para>
       </listitem>
      </varlistentry>
@@ -230,11 +225,18 @@
       <term><option>--use-list=<replaceable class="parameter">list-file</replaceable></option></term>
       <listitem>
        <para>
-        Restore elements in <replaceable class="PARAMETER">
-        list-file</replaceable> only, and in the
-        order they appear in the file. Lines can be moved and may also
-        be commented out by placing a <literal>;</literal> at the
-        start of the line.  (See below for examples.)
+        Restore only those archive elements that are listed in <replaceable
+        class="PARAMETER">list-file</replaceable>, and restore them in the
+        order they appear in the file.  Note that
+        if filtering switches such as <option>-n</> or <option>-t</> are
+        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>
