Make discussion of names clearer and more accurate.

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 918d91a05cff7e39369792dec4ed3cca6865f90c..30f57e5ccf6048db2dc9955e668366ca54d85958 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -340,17 +340,23 @@ A comment beginning with "/*" extends to the first occurrence of "*/".
    <title>Names</title>
 
    <para>
-    Names in SQL are sequences of less than NAMEDATALEN alphanumeric characters,
-    starting with an alphabetic character.  By default, NAMEDATALEN is set
-    to 32  (but at the time the system is built, NAMEDATALEN can be changed
-    by changing the <literal>#define</literal> in
-    src/backend/include/postgres.h).
-    Underscore ("_") is considered an alphabetic character.
+    Names in SQL must begin with a letter
+    (<literal>a</literal>-<literal>z</literal>) or underscore
+    (<literal>_</literal>).
+    Subsequent characters in a name can be letters, digits
+    (<literal>0</literal>-<literal>9</literal>),
+    or underscores.  The system uses no more than NAMEDATALEN-1 characters
+    of a name; longer names can be written in queries, but they will be
+    truncated.
+    By default, NAMEDATALEN is 32 so the maximum name length is 31 (but
+    at the time the system is built, NAMEDATALEN can be changed in
+    src/include/postgres_ext.h).
    </para>
 
    <para>
     Names containing other characters may be formed by surrounding them
-    with double quotes.  For example, table or column names may contain
+    with double quotes (<literal>"</literal>).  For example, table or column
+    names may contain
     otherwise disallowed characters such as spaces, ampersands, etc. if
     quoted.  Quoting a name also makes it case-sensitive,
     whereas unquoted names are always folded to lower case.  For example,
@@ -359,6 +365,12 @@ A comment beginning with "/*" extends to the first occurrence of "*/".
     considered the same by <productname>Postgres</productname>, but
     <literal>"Foo"</literal> is a different name.
    </para>
+
+   <para>
+    Double quotes can also be used to protect a name that would otherwise
+    be taken to be an SQL keyword.  For example, <literal>IN</literal>
+    is a keyword but <literal>"IN"</literal> is a name.
+   </para>
   </sect1>
 
   <sect1>