docs/parser.md: Improve.

1 files changed, 18 insertions, 15 deletions

diff --git a/docs/parser.md b/docs/parser.md
index 41ae7d6..a23ebbc 100644
--- a/docs/parser.md
+++ b/docs/parser.md
@@ -10,8 +10,12 @@ expressions and data types:
     | E.G.   | foo, |foo bar|  | #name  | (X & Y)  | ()   |
     +--------+-----------------+--------+----------+------+
 
+Note that the ampersand replaces the period in pair notation.  This simplifies
+the grammar: periods are a regular constituent of strings, while the ampersand
+cannot appear in unquoted strings.
+
 The parser can also output non-negative integers, but this is only used for
-datum labels; number literals are handled by the decoder (see next section).
+datum labels; number literals are handled by the *decoder*.
 
 The parser recognizes various "syntax sugar" and transforms it into uses of the
 above data types.  The most ubiquitous example is of course the list:
@@ -34,14 +38,14 @@ The following table summarizes the other supported transformations:
 
                                       #%hex=datum  -> (#LABEL hex & datum)
 
-A separate process called "decoding" can transform such data into more complex
+A separate process called *decoding* can transform such data into more complex
 types.  For example, `(#HASH x y z)` could be decoded into a vector, so the
-expression `#(x y z)` works just like in Scheme.  See the next section for
-details about the decoder.
+expression `#(x y z)` works just like in Scheme.
 
-Decoding also resolves datum labels, and goes over bare strings to find ones
-that are actually a number literal.  This lets us offload the complexity of
-number parsing elsewhere, so the parser remains extremely simple.
+Decoding also resolves datum labels, goes over strings to find ones that are
+actually a number literal, and takes care of a number of other transformations.
+This offloads complexity, allowing the parser to remain extremely simple.  See
+the dedicated documentation of the decoder for more.
 
 Further notes about the syntax sugar table and examples above:
 
@@ -50,11 +54,10 @@ Further notes about the syntax sugar table and examples above:
 
 * The `#datum` form only applies when the datum following the hash sign is a
   list, quoted string, quote expression, another expression starting with the
-  hash sign, or a pipe-quoted bare string (see next).  A bare string can follow
-  the hash sign by separating the two with a backslash: `#\string`
+  hash sign, or a pipe-quoted string (see next).  A bare string can follow the
+  hash sign by separating the two with a backslash: `#\string`
 
-* Bare strings can be "quoted" with pipes as in Scheme; it should be noted that
-  this still produces a "bare string" in terms of data type:
+* Strings can be quoted with pipes, like symbols in Scheme:
 
       |foo bar baz|
 
@@ -102,10 +105,10 @@ Further notes about the syntax sugar table and examples above:
 
       foo(x y) -> (#JOIN foo (x y))          foo(x y) -> (#JOIN foo x y)
 
-* Runes are case-sensitive, and the parser only emits runes using upper-case
-  letters when expressing syntax sugar.  This way, there can be no accidental
-  clash with runes that appear verbatim in code, as long as only lower-case
-  letters are used for rune literals in code.
+* Runes are case-sensitive, and the parser always emits runes using upper-case
+  letters when expressing syntax sugar.  Uppercase rune names are reserved for
+  Zisp's internal use and standard library; users can use lowercase runes with
+  custom meaning without worrying about clashes.
 
 <!--
 ;; Local Variables: