Try to improve the clarity of the psql documentation for the \d family of

commands, as per recent discussion.  Includes suggestions from Adrian Klaver
and Filip Rembialkowski.

1 files changed, 111 insertions, 99 deletions

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index dc8a4819dfe..5b8bb836b18 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.235 2009/11/25 20:26:30 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.236 2009/12/24 23:36:39 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -635,8 +635,7 @@ testdb=&gt;
     meta-command that is processed by <application>psql</application>
     itself. These commands help make
     <application>psql</application> more useful for administration or
-    scripting. Meta-commands are more commonly called slash or backslash
-    commands.
+    scripting. Meta-commands are often called slash or backslash commands.
     </para>
 
     <para>
@@ -684,8 +683,9 @@ testdb=&gt;
     </para>
 
     <para>
-    Parsing for arguments stops when another unquoted backslash occurs.
-    This is taken as the beginning of a new meta-command. The special
+    Parsing for arguments stops at the end of the line, or when another
+    unquoted backslash is found.  An unquoted backslash
+    is taken as the beginning of a new meta-command. The special
     sequence <literal>\\</literal> (two backslashes) marks the end of
     arguments and continues parsing <acronym>SQL</acronym> commands, if
     any. That way <acronym>SQL</acronym> and
@@ -846,24 +846,26 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\d[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\d[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
         For each relation (table, view, index, or sequence) matching the
         <replaceable class="parameter">pattern</replaceable>, show all
-        columns, their types, the tablespace (if not the default) and any special
-        attributes such as <literal>NOT NULL</literal> or defaults, if
-        any. Associated indexes, constraints, rules, and triggers are
-        also shown, as is the view definition if the relation is a view.
-        (<quote>Matching the pattern</> is defined below.)
+        columns, their types, the tablespace (if not the default) and any
+        special attributes such as <literal>NOT NULL</literal> or defaults.
+        Associated indexes, constraints, rules, and triggers are
+        also shown.
+        (<quote>Matching the pattern</> is defined in
+        <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">
+        below.)
         </para>
 
         <para>
         The command form <literal>\d+</literal> is identical, except that
         more information is displayed: any comments associated with the
         columns of the table are shown, as is the presence of OIDs in the
-        table.
+        table, and the view definition if the relation is a view.
         </para>
 
         <para>
@@ -877,7 +879,7 @@ testdb=&gt;
         If <command>\d</command> is used without a
         <replaceable class="parameter">pattern</replaceable> argument, it is
         equivalent to <command>\dtvs</command> which will show a list of
-        all tables, views, and sequences. This is purely a convenience
+        all visible tables, views, and sequences. This is purely a convenience
         measure.
         </para>
         </note>
@@ -885,11 +887,11 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\da[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\da[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
-        Lists all available aggregate functions, together with their
+        Lists aggregate functions, together with their
         return type and the data types they operate on. If <replaceable
         class="parameter">pattern</replaceable>
         is specified, only aggregates whose names match the pattern are shown.
@@ -902,11 +904,11 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\db[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\db[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
-        Lists all available tablespaces. If <replaceable
+        Lists tablespaces. If <replaceable
         class="parameter">pattern</replaceable>
         is specified, only tablespaces whose names match the pattern are shown.
         If <literal>+</literal> is appended to the command name, each object
@@ -917,10 +919,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dc[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dc[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all available conversions between character-set encodings.
+        Lists conversions between character-set encodings.
         If <replaceable class="parameter">pattern</replaceable>
         is specified, only conversions whose names match the pattern are
         listed.
@@ -933,10 +935,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dC [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dC [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all available type casts.
+        Lists type casts.
         If <replaceable class="parameter">pattern</replaceable>
         is specified, only casts whose source or target types match the
         pattern are listed.
@@ -946,7 +948,7 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dd[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dd[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
         Shows the descriptions of objects matching the <replaceable
@@ -979,7 +981,7 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\ddp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\ddp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
         Lists default access privilege settings.  An entry is shown for
@@ -1002,12 +1004,12 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dD[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dD[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all available domains. If <replaceable
+        Lists domains. If <replaceable
         class="parameter">pattern</replaceable>
-        is specified, only matching domains are shown.
+        is specified, only domains whose names match the pattern are shown.
         By default, only user-created objects are shown;  supply a
         pattern or the <literal>S</literal> modifier to include system
         objects.
@@ -1017,10 +1019,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\des[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\des[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all foreign servers (mnemonic: <quote>external
+        Lists foreign servers (mnemonic: <quote>external
         servers</quote>).
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only those servers whose name matches the pattern
@@ -1033,10 +1035,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\deu[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\deu[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all user mappings (mnemonic: <quote>external
+        Lists user mappings (mnemonic: <quote>external
         users</quote>).
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only those mappings whose user names match the
@@ -1056,10 +1058,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dew[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dew[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all foreign-data wrappers (mnemonic: <quote>external
+        Lists foreign-data wrappers (mnemonic: <quote>external
         wrappers</quote>).
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only those foreign-data wrappers whose name matches
@@ -1072,40 +1074,42 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\df[antwS+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\df[antwS+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
-        Lists available functions, together with their arguments,
-        return types, and their function types: 'agg' (aggregate),
-        'normal', 'trigger', and 'window'.  To display only functions
-        of a specific type, use the corresponding letters <literal>a</>,
-        <literal>n</>, <literal>t</>, or <literal>w</>.  If <replaceable
+        Lists functions, together with their arguments, return types, and
+        function types, which are classified as <quote>agg</> (aggregate),
+        <quote>normal</>, <quote>trigger</>, or <quote>window</>.
+        To display only functions
+        of specific type(s), add the corresponding letters <literal>a</>,
+        <literal>n</>, <literal>t</>, or <literal>w</> to the command.
+        If <replaceable
         class="parameter">pattern</replaceable> is specified, only
         functions whose names match the pattern are shown.  If the
         form <literal>\df+</literal> is used, additional information
         about each function, including volatility, language, source
         code and description, is shown.  By default, only user-created
-        objects are shown;  supply a pattern or the <literal>S</literal>
+        objects are shown; supply a pattern or the <literal>S</literal>
         modifier to include system objects.
         </para>
 
-        <note>
+        <tip>
         <para>
         To look up functions taking arguments or returning values of a specific
-        type, use your pager's search capability to scroll through the <literal>\df</>
-        output.
+        type, use your pager's search capability to scroll through the
+        <literal>\df</> output.
         </para>
-        </note>
+        </tip>
 
         </listitem>
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\dF[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dF[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-         Lists available text search configurations.
+         Lists text search configurations.
          If <replaceable class="parameter">pattern</replaceable> is specified,
          only configurations whose names match the pattern are shown.
          If the form <literal>\dF+</literal> is used, a full description of
@@ -1116,10 +1120,10 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\dFd[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dFd[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-         Lists available text search dictionaries.
+         Lists text search dictionaries.
          If <replaceable class="parameter">pattern</replaceable> is specified,
          only dictionaries whose names match the pattern are shown.
          If the form <literal>\dFd+</literal> is used, additional information
@@ -1130,10 +1134,10 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\dFp[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dFp[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-         Lists available text search parsers.
+         Lists text search parsers.
          If <replaceable class="parameter">pattern</replaceable> is specified,
          only parsers whose names match the pattern are shown.
          If the form <literal>\dFp+</literal> is used, a full description of
@@ -1144,10 +1148,10 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\dFt[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dFt[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-         Lists available text search templates.
+         Lists text search templates.
          If <replaceable class="parameter">pattern</replaceable> is specified,
          only templates whose names match the pattern are shown.
          If the form <literal>\dFt+</literal> is used, additional information
@@ -1158,10 +1162,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dg[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dg[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all database roles. If <replaceable
+        Lists database roles. If <replaceable
         class="parameter">pattern</replaceable> is specified, only
         those roles whose names match the pattern are listed.
         (This command is now effectively the same as <literal>\du</literal>).
@@ -1173,10 +1177,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\di[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
-        <term><literal>\ds[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
-        <term><literal>\dt[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
-        <term><literal>\dv[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\di[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+        <term><literal>\ds[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+        <term><literal>\dt[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+        <term><literal>\dv[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
@@ -1185,19 +1189,16 @@ testdb=&gt;
         <literal>t</literal>, and <literal>v</literal>
         stand for index, sequence, table, and view, respectively.
         You can specify any or all of
-        these letters, in any order, to obtain a listing of all the
-        matching objects.  For example, <literal>\dit</> lists indexes
+        these letters, in any order, to obtain a listing of objects
+        of these types.  For example, <literal>\dit</> lists indexes
         and tables.  If <literal>+</literal> is
         appended to the command name, each object is listed with its
         physical size on disk and its associated description, if any.
-        By default, only user-created objects are shown;  supply a
-        pattern or the <literal>S</literal> modifier to include system
-        objects.
-        </para>
-
-        <para>
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only objects whose names match the pattern are listed.
+        By default, only user-created objects are shown; supply a
+        pattern or the <literal>S</literal> modifier to include system
+        objects.
         </para>
         </listitem>
       </varlistentry>
@@ -1215,12 +1216,12 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dn[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dn[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
 
         <listitem>
         <para>
-        Lists available schemas (namespaces). If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
+        Lists schemas (namespaces). If <replaceable
+        class="parameter">pattern</replaceable>
         is specified, only schemas whose names match the pattern are listed.
         Non-local temporary schemas are suppressed.  If <literal>+</literal>
         is appended to the command name, each object is listed with its associated
@@ -1231,10 +1232,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\do[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\do[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists available operators with their operand and return types.
+        Lists operators with their operand and return types.
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only operators whose names match the pattern are listed.
         By default, only user-created objects are shown;  supply a
@@ -1246,13 +1247,14 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\dp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists available tables, views and sequences with their
+        Lists tables, views and sequences with their
         associated access privileges.
         If <replaceable class="parameter">pattern</replaceable> is
-        specified, only tables, views and sequences whose names match the pattern are listed.
+        specified, only tables, views and sequences whose names match the
+        pattern are listed.
         </para>
 
         <para>
@@ -1266,30 +1268,32 @@ testdb=&gt;
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\drds [ <replaceable class="parameter">role-pattern</replaceable> [ <replaceable class="parameter">database-pattern </replaceable> ] ]</literal></term>
+        <term><literal>\drds [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">role-pattern</replaceable></link> [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">database-pattern</replaceable></link> ] ]</literal></term>
         <listitem>
         <para>
-        Lists defined configuration settings.  These settings can be role-specific,
-        database-specific, or both.  <literal>role-pattern</literal> and
-        <literal>database-pattern</literal> are used to select
-        specific roles and database to list, respectively; if omitted, or * is specified,
-        all settings are listed, including those not role-specific or database-specific,
-        respectively.
+        Lists defined configuration settings.  These settings can be
+        role-specific, database-specific, or both.
+        <replaceable>role-pattern</replaceable> and
+        <replaceable>database-pattern</replaceable> are used to select
+        specific roles and databases to list, respectively.  If omitted, or if
+        <literal>*</> is specified, all settings are listed, including those
+        not role-specific or database-specific, respectively.
         </para>
 
         <para>
         The <xref linkend="sql-alterrole" endterm="sql-alterrole-title"> and
         <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
-        commands are used to define per-database role configuration settings.
+        commands are used to define per-role and per-database configuration
+        settings.
         </para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\dT[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\dT[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists available data types.
+        Lists data types.
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only types whose names match the pattern are listed.
         If <literal>+</literal> is appended to the command name, each type is
@@ -1304,10 +1308,10 @@ testdb=&gt;
 
 
       <varlistentry>
-        <term><literal>\du[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\du[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Lists all database roles. If <replaceable
+        Lists database roles. If <replaceable
         class="parameter">pattern</replaceable> is specified, only
         those roles whose names match the pattern are listed.
         If the form <literal>\du+</literal> is used, additional information
@@ -2132,7 +2136,8 @@ lo_import 152801
 
 
       <varlistentry>
-        <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+        <term><literal>\w</literal> <replaceable class="parameter">filename</replaceable></term>
+        <term><literal>\w</literal> <literal>|</><replaceable class="parameter">command</replaceable></term>
         <listitem>
         <para>
         Outputs the current query buffer to the file <replaceable
@@ -2155,13 +2160,14 @@ lo_import 152801
 
 
       <varlistentry>
-        <term><literal>\z [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\z [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
         <listitem>
         <para>
-        Produces a list of all available tables, views and sequences with their
+        Lists tables, views and sequences with their
         associated access privileges.
         If a <replaceable class="parameter">pattern</replaceable> is
-        specified, only tables,views and sequences whose names match the pattern are listed.
+        specified, only tables, views and sequences whose names match the
+        pattern are listed.
         </para>
 
         <para>
@@ -2179,7 +2185,7 @@ lo_import 152801
         Escapes to a separate Unix shell or executes the Unix command
         <replaceable class="parameter">command</replaceable>. The
         arguments are not further interpreted, the shell will see them
-        as is.
+        as-is.
         </para>
         </listitem>
       </varlistentry>
@@ -2225,10 +2231,24 @@ lo_import 152801
   </para>
 
   <para>
+   Whenever the <replaceable class="parameter">pattern</replaceable> parameter
+   is omitted completely, the <literal>\d</> commands display all objects
+   that are visible in the current schema search path &mdash; this is
+   equivalent to using <literal>*</> as the pattern.
+   (An object is said to be <firstterm>visible</> if its
+   containing schema is in the search path and no object of the same
+   kind and name appears earlier in the search path. This is equivalent to the
+   statement that the object can be referenced by name without explicit
+   schema qualification.)
+   To see all objects in the database regardless of visibility,
+   use <literal>*.*</> as the pattern.
+  </para>
+
+  <para>
    Within a pattern, <literal>*</> matches any sequence of characters
    (including no characters) and <literal>?</> matches any single character.
    (This notation is comparable to Unix shell file name patterns.)
-   For example, <literal>\dt int*</> displays all tables whose names
+   For example, <literal>\dt int*</> displays tables whose names
    begin with <literal>int</>.  But within double quotes, <literal>*</>
    and <literal>?</> lose these special meanings and are just matched
    literally.
@@ -2270,14 +2290,6 @@ lo_import 152801
    expression special characters are matched literally in operator name
    patterns (i.e., the argument of <literal>\do</>).
   </para>
-
-  <para>
-   Whenever the <replaceable class="parameter">pattern</replaceable> parameter
-   is omitted completely, the <literal>\d</> commands display all objects
-   that are visible in the current schema search path &mdash; this is
-   equivalent to using the pattern <literal>*</>.
-   To see all objects in the database, use the pattern <literal>*.*</>.
-  </para>
   </refsect3>
  </refsect2>