projects / postgresql.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 0ef5910)
Try to improve the clarity of the psql documentation for the \d family of
authorTom Lane
Thu, 24 Dec 2009 23:36:39 +0000 (23:36 +0000)
committerTom Lane
Thu, 24 Dec 2009 23:36:39 +0000 (23:36 +0000)
commands, as per recent discussion.  Includes suggestions from Adrian Klaver
and Filip Rembialkowski.

doc/src/sgml/ref/psql-ref.sgml patch | blob | blame | history

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index dc8a4819dfe14e6f879e75bba9cab0f6c84b8845..5b8bb836b182de4c7c17b43698133d6994d5cbac 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 
 
@@ -635,8 +635,7 @@ testdb=>
     meta-command that is processed by psql
     itself. These commands help make
     psql 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.
     
 
     
@@ -684,8 +683,9 @@ testdb=>
     
 
     
-    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 \\ (two backslashes) marks the end of
     arguments and continues parsing SQL commands, if
     any. That way SQL and
@@ -846,24 +846,26 @@ testdb=>
       
 
       
-        \d[S+] [ <replaceable class="parameter">pattern> ]
+        \d[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
         For each relation (table, view, index, or sequence) matching the
         pattern, show all
-        columns, their types, the tablespace (if not the default) and any special
-        attributes such as NOT NULL or defaults, if
-        any. Associated indexes, constraints, rules, and triggers are
-        also shown, as is the view definition if the relation is a view.
-        (Matching the pattern is defined below.)
+        columns, their types, the tablespace (if not the default) and any
+        special attributes such as NOT NULL or defaults.
+        Associated indexes, constraints, rules, and triggers are
+        also shown.
+        (Matching the pattern is defined in
+        
+        below.)
         
 
         
         The command form \d+ 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.
         
 
         
@@ -877,7 +879,7 @@ testdb=>
         If \d is used without a
         pattern argument, it is
         equivalent to \dtvs 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.
         
         
@@ -885,11 +887,11 @@ testdb=>
       
 
       
-        \da[S] [ <replaceable class="parameter">pattern> ]
+        \da[S] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
-        Lists all available aggregate functions, together with their
+        Lists aggregate functions, together with their
         return type and the data types they operate on. If 
         class="parameter">pattern
         is specified, only aggregates whose names match the pattern are shown.
@@ -902,11 +904,11 @@ testdb=>
 
 
       
-        \db[+] [ <replaceable class="parameter">pattern> ]
+        \db[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
-        Lists all available tablespaces. If 
+        Lists tablespaces. If 
         class="parameter">pattern
         is specified, only tablespaces whose names match the pattern are shown.
         If + is appended to the command name, each object
@@ -917,10 +919,10 @@ testdb=>
 
 
       
-        \dc[S] [ <replaceable class="parameter">pattern> ]
+        \dc[S] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all available conversions between character-set encodings.
+        Lists conversions between character-set encodings.
         If pattern
         is specified, only conversions whose names match the pattern are
         listed.
@@ -933,10 +935,10 @@ testdb=>
 
 
       
-        \dC [ <replaceable class="parameter">pattern> ]
+        \dC [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all available type casts.
+        Lists type casts.
         If pattern
         is specified, only casts whose source or target types match the
         pattern are listed.
@@ -946,7 +948,7 @@ testdb=>
 
 
       
-        \dd[S] [ <replaceable class="parameter">pattern> ]
+        \dd[S] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
         Shows the descriptions of objects matching the 
@@ -979,7 +981,7 @@ testdb=>
 
 
       
-        \ddp [ <replaceable class="parameter">pattern> ]
+        \ddp [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
         Lists default access privilege settings.  An entry is shown for
@@ -1002,12 +1004,12 @@ testdb=>
 
 
       
-        \dD[S] [ <replaceable class="parameter">pattern> ]
+        \dD[S] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all available domains. If 
+        Lists domains. If 
         class="parameter">pattern
-        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 S modifier to include system
         objects.
@@ -1017,10 +1019,10 @@ testdb=>
 
 
       
-        \des[+] [ <replaceable class="parameter">pattern> ]
+        \des[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all foreign servers (mnemonic: external
+        Lists foreign servers (mnemonic: external
         servers).
         If pattern is
         specified, only those servers whose name matches the pattern
@@ -1033,10 +1035,10 @@ testdb=>
 
 
       
-        \deu[+] [ <replaceable class="parameter">pattern> ]
+        \deu[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all user mappings (mnemonic: external
+        Lists user mappings (mnemonic: external
         users).
         If pattern is
         specified, only those mappings whose user names match the
@@ -1056,10 +1058,10 @@ testdb=>
 
 
       
-        \dew[+] [ <replaceable class="parameter">pattern> ]
+        \dew[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all foreign-data wrappers (mnemonic: external
+        Lists foreign-data wrappers (mnemonic: external
         wrappers).
         If pattern is
         specified, only those foreign-data wrappers whose name matches
@@ -1072,40 +1074,42 @@ testdb=>
 
 
       
-        \df[antwS+] [ <replaceable class="parameter">pattern> ]
+        \df[antwS+] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
-        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 a,
-        n, t, or w.  If 
+        Lists functions, together with their arguments, return types, and
+        function types, which are classified as agg (aggregate),
+        normal, trigger, or window.
+        To display only functions
+        of specific type(s), add the corresponding letters a,
+        n, t, or w to the command.
+        If 
         class="parameter">pattern is specified, only
         functions whose names match the pattern are shown.  If the
         form \df+ 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 S
+        objects are shown; supply a pattern or the S
         modifier to include system objects.
         
 
-        <note>
+        <tip>
         
         To look up functions taking arguments or returning values of a specific
-        type, use your pager's search capability to scroll through the \df
-        output.
+        type, use your pager's search capability to scroll through the
+        \df output.
         
-        note>
+        tip>
 
         
       
 
       
-        \dF[+] [ <replaceable class="parameter">pattern> ]
+        \dF[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-         Lists available text search configurations.
+         Lists text search configurations.
          If pattern is specified,
          only configurations whose names match the pattern are shown.
          If the form \dF+ is used, a full description of
@@ -1116,10 +1120,10 @@ testdb=>
       
 
       
-        \dFd[+] [ <replaceable class="parameter">pattern> ]
+        \dFd[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-         Lists available text search dictionaries.
+         Lists text search dictionaries.
          If pattern is specified,
          only dictionaries whose names match the pattern are shown.
          If the form \dFd+ is used, additional information
@@ -1130,10 +1134,10 @@ testdb=>
       
 
       
-        \dFp[+] [ <replaceable class="parameter">pattern> ]
+        \dFp[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-         Lists available text search parsers.
+         Lists text search parsers.
          If pattern is specified,
          only parsers whose names match the pattern are shown.
          If the form \dFp+ is used, a full description of
@@ -1144,10 +1148,10 @@ testdb=>
       
 
       
-        \dFt[+] [ <replaceable class="parameter">pattern> ]
+        \dFt[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-         Lists available text search templates.
+         Lists text search templates.
          If pattern is specified,
          only templates whose names match the pattern are shown.
          If the form \dFt+ is used, additional information
@@ -1158,10 +1162,10 @@ testdb=>
 
 
       
-        \dg[+] [ <replaceable class="parameter">pattern> ]
+        \dg[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all database roles. If 
+        Lists database roles. If 
         class="parameter">pattern is specified, only
         those roles whose names match the pattern are listed.
         (This command is now effectively the same as \du).
@@ -1173,10 +1177,10 @@ testdb=>
 
 
       
-        \di[S+] [ <replaceable class="parameter">pattern> ]
-        \ds[S+] [ <replaceable class="parameter">pattern> ]
-        \dt[S+] [ <replaceable class="parameter">pattern> ]
-        \dv[S+] [ <replaceable class="parameter">pattern> ]
+        \di[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
+        \ds[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
+        \dt[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
+        \dv[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
@@ -1185,19 +1189,16 @@ testdb=>
         t, and v
         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, \dit lists indexes
+        these letters, in any order, to obtain a listing of objects
+        of these types.  For example, \dit lists indexes
         and tables.  If + 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 S modifier to include system
-        objects.
-        
-
-        
         If pattern is
         specified, only objects whose names match the pattern are listed.
+        By default, only user-created objects are shown; supply a
+        pattern or the S modifier to include system
+        objects.
         
         
       
@@ -1215,12 +1216,12 @@ testdb=>
 
 
       
-        \dn[+] [ <replaceable class="parameter">pattern> ]
+        \dn[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
 
         
         
-        Lists available schemas (namespaces). If 
-        class="parameter">pattern (a regular expression)
+        Lists schemas (namespaces). If 
+        class="parameter">pattern
         is specified, only schemas whose names match the pattern are listed.
         Non-local temporary schemas are suppressed.  If +
         is appended to the command name, each object is listed with its associated
@@ -1231,10 +1232,10 @@ testdb=>
 
 
       
-        \do[S] [ <replaceable class="parameter">pattern> ]
+        \do[S] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists available operators with their operand and return types.
+        Lists operators with their operand and return types.
         If pattern 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=>
 
 
       
-        \dp [ <replaceable class="parameter">pattern> ]
+        \dp [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists available tables, views and sequences with their
+        Lists tables, views and sequences with their
         associated access privileges.
         If pattern 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.
         
 
         
@@ -1266,30 +1268,32 @@ testdb=>
       
 
       
-        \drds [ <replaceable class="parameter">role-pattern [ database-pattern > ] ]
+        \drds [ <link linkend="APP-PSQL-patterns">role-pattern [ database-pattern> ] ]
         
         
-        Lists defined configuration settings.  These settings can be role-specific,
-        database-specific, or both.  role-pattern and
-        database-pattern 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.
+        role-pattern and
+        database-pattern are used to select
+        specific roles and databases to list, respectively.  If omitted, or if
+        * is specified, all settings are listed, including those
+        not role-specific or database-specific, respectively.
         
 
         
         The  and
         
-        commands are used to define per-database role configuration settings.
+        commands are used to define per-role and per-database configuration
+        settings.
         
         
       
 
       
-        \dT[S+] [ <replaceable class="parameter">pattern> ]
+        \dT[S+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists available data types.
+        Lists data types.
         If pattern is
         specified, only types whose names match the pattern are listed.
         If + is appended to the command name, each type is
@@ -1304,10 +1308,10 @@ testdb=>
 
 
       
-        \du[+] [ <replaceable class="parameter">pattern> ]
+        \du[+] [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Lists all database roles. If 
+        Lists database roles. If 
         class="parameter">pattern is specified, only
         those roles whose names match the pattern are listed.
         If the form \du+ is used, additional information
@@ -2132,7 +2136,8 @@ lo_import 152801
 
 
       
-        \w {filename | |command}
+        \w filename
+        \w |command
         
         
         Outputs the current query buffer to the file 
@@ -2155,13 +2160,14 @@ lo_import 152801
 
 
       
-        \z [ <replaceable class="parameter">pattern> ]
+        \z [ <link linkend="APP-PSQL-patterns">pattern> ]
         
         
-        Produces a list of all available tables, views and sequences with their
+        Lists tables, views and sequences with their
         associated access privileges.
         If a pattern 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.
         
 
         
@@ -2179,7 +2185,7 @@ lo_import 152801
         Escapes to a separate Unix shell or executes the Unix command
         command. The
         arguments are not further interpreted, the shell will see them
-        as is.
+        as-is.
         
         
       
@@ -2224,11 +2230,25 @@ lo_import 152801
    the table named fooFOObar.
   
 
+  
+   Whenever the pattern parameter
+   is omitted completely, the \d commands display all objects
+   that are visible in the current schema search path — this is
+   equivalent to using * as the pattern.
+   (An object is said to be 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 *.* as the pattern.
+  
+
   
    Within a pattern, * matches any sequence of characters
    (including no characters) and ? matches any single character.
    (This notation is comparable to Unix shell file name patterns.)
-   For example, \dt int* displays all tables whose names
+   For example, \dt int* displays tables whose names
    begin with int.  But within double quotes, *
    and ? 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 \do).
   
-
-  
-   Whenever the pattern parameter
-   is omitted completely, the \d commands display all objects
-   that are visible in the current schema search path — this is
-   equivalent to using the pattern *.
-   To see all objects in the database, use the pattern *.*.
-  
   
  
 
This is the main PostgreSQL git repository.