1 files changed, 16 insertions, 9 deletions
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 332464429cd..918d91a05cf 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -315,12 +315,11 @@ UNCOMMITTED UNNAMED
 
    <para>
     A <firstterm>comment</firstterm>
-    is an arbitrary sequence of characters following double dashes up to the end
-    of the line.  We also support double-slashes as comments, e.g.:
+    is an arbitrary sequence of characters beginning with double dashes
+    and extending to the end of the line, e.g.:
 
     <programlisting>
 -- This is a standard SQL comment
-// And this is another supported comment style, like C++
     </programlisting>
 
 We also support C-style block comments, e.g.:
@@ -331,6 +330,9 @@ We also support C-style block comments, e.g.:
    comment
  */
     </programlisting>
+
+A comment beginning with "/*" extends to the first occurrence of "*/".
+
    </para>
   </sect1>
 
@@ -340,17 +342,22 @@ We also support C-style block comments, e.g.:
    <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
+    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.
+    src/backend/include/postgres.h).
     Underscore ("_") is considered an alphabetic character.
    </para>
 
    <para>
-    In some contexts, names may contain other characters if surrounded 
-    by double quotes. For example, table or column names may contain otherwise
-    disallowed characters such as spaces, ampersands, etc. using this
-    technique.
+    Names containing other characters may be formed by surrounding them
+    with double quotes.  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,
+    the names <literal>FOO</literal>, <literal>foo</literal>
+    and <literal>"foo"</literal> are
+    considered the same by <productname>Postgres</productname>, but
+    <literal>"Foo"</literal> is a different name.
    </para>
   </sect1>