Improve description of the pattern matching rules used by psql's \d

commands (and soon by pg_dump).

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 15f5d7424e844539a1b4783c64c68a4a98eb2f02..fae6984f26befb7ba8375a4addb896c1476fa121 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 
 
@@ -1817,34 +1817,85 @@ lo_import 152801
     
   
 
+  
+   Patterns
+
+   
+    patterns
+    in psql and pg_dump
+   
+
   
    The various \d commands accept a 
    class="parameter">pattern parameter to specify the
-   object name(s) to be displayed.  * means any
-   sequence of characters and ? means any single
-   character.  (This notation is comparable to Unix shell file name
-   patterns.)  Advanced users can also use regular-expression
-   notations such as character classes, for example [0-9]
-   to match any digit.  To make any of these
-   pattern-matching characters be interpreted literally, surround it
-   with double quotes.
+   object name(s) to be displayed.  In the simplest case, a pattern
+   is just the exact name of the object.  The characters within a
+   pattern are normally folded to lower case, just as in SQL names;
+   for example, \dt FOO will display the table named
+   foo.  As in SQL names, placing double quotes around
+   a pattern stops folding to lower case.  Should you need to include
+   an actual double quote character in a pattern, write it as a pair
+   of double quotes within a double-quote sequence; again this is in
+   accord with the rules for SQL quoted identifiers.  For example,
+   \dt "FOO""BAR" will display the table named
+   FOO"BAR (not foo"bar).  Unlike the normal
+   rules for SQL names, you can put double quotes around just part
+   of a pattern, for instance \dt FOO"FOO"BAR will display
+   the table named fooFOObar.
+  
+
+  
+   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
+   begin with int.  But within double quotes, *
+   and ? lose these special meanings and are just matched
+   literally.
   
 
   
-   A pattern that contains an (unquoted) dot is interpreted as a schema
+   A pattern that contains a dot (.) is interpreted as a schema
    name pattern followed by an object name pattern.  For example,
-   \dt foo*.bar* displays all tables in schemas whose name
-   starts with foo and whose table name
-   starts with bar.  If no dot appears, then the pattern
+   \dt foo*.bar* displays all tables whose table name
+   starts with bar that are in schemas whose schema name
+   starts with foo.  When no dot appears, then the pattern
    matches only objects that are visible in the current schema search path.
+   Again, a dot within double quotes loses its special meaning and is matched
+   literally.
+  
+
+  
+   Advanced users can use regular-expression notations such as character
+   classes, for example [0-9] to match any digit.  All regular
+   expression special characters work as specified in
+   , except for . which
+   is taken as a separator as mentioned above, * which is
+   translated to the regular-expression notation .*, and
+   ? which is translated to ..  You can emulate
+   these pattern characters at need by writing
+   ? for .,
+   (R+|) for
+   R*, or
+   (R|) for
+   R?.
+   Remember that the pattern must match the whole name, unlike the usual
+   interpretation of regular expressions; write * at the beginning
+   and/or end if you don't wish the pattern to be anchored.
+   Note that within double quotes, all regular expression special characters
+   lose their special meanings and are matched literally.  Also, the regular
+   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.  To see all objects
-   in the database, use the pattern *.*.
+   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 *.*.
   
+