more on allowed variable names. closes #3945

doc/manual/variables.rst

@@ -4,8 +4,8 @@
 ***********
 
 Julia provides an extremely flexible system for naming variables.
-Capitalization carries no semantic meaning, nor does the first letter of a
-variable.
+Variable names are case-sensitive, and have no semantic meaning (that is,
+the language will not treat variables differently based on their names).
 
 .. raw:: latex
 
@@ -32,7 +32,7 @@ variable.
 
     \end{CJK*}
 
-They can even be given Unicode names:
+Unicode names (in UTF-8 encoding) are allowed:
 
 .. raw:: latex
 
@@ -67,6 +67,17 @@ Julia will even let you redefine built-in constants and functions if needed::
     
 However, this is obviously not recommended to avoid potential confusion.
 
+Allowed Variable Names
+======================
+
+Variable names must begin with a letter (A-Z or a-z), underscore, or Unicode
+character with code point greater than 00A0. Subsequent characters may also include
+! and digits (0-9).
+
+All operators are also valid identifiers, but are parsed specially. In some
+contexts operators can be used just like variables; for example ``(+)`` refers
+to the addition function, and ``(+) = f`` will reassign it.
+
 The only explicitly disallowed names for variables are the names of built-in
 statements::
 
@@ -77,18 +88,18 @@ statements::
     ERROR: syntax: unexpected =
 
 
-Stylistic convention
-====================
+Stylistic Conventions
+=====================
 
 While Julia imposes few restrictions on valid names, it has become useful to
-adopt the following conventions on names in Julia:
+adopt the following conventions:
 
-- Names of variables are in lower case, with word separation indicated by
-  underscores (``'\_'``).
+- Names of variables are in lower case.
+- Word separation can be indicated by underscores (``'\_'``), but use of
+  underscores is discouraged unless the name would be hard to read otherwise.
 - Names of ``Type``\ s begin with a capital letter and word separation is
   shown with CamelCase instead of underscores.
 - Names of ``function``\ s and ``macro``\s are in lower case, without
   underscores.
 - Functions that modify their inputs have names that end in ``!``. These
   functions are sometimes called mutating functions or in-place functions.
-