Last parser doc touch up before I move on.

1 files changed, 24 insertions, 21 deletions

diff --git a/doc/c1/1-parse.md b/doc/c1/1-parse.md
index 4a8c22b..babf160 100644
--- a/doc/c1/1-parse.md
+++ b/doc/c1/1-parse.md
@@ -11,9 +11,27 @@ which is necessary to strategically construct more complex values:
     | E.G.  | foobar  | #name  | (X & Y)  | ()   |
     +-------+---------+--------+----------+------+
 
-The parser also recognizes various *syntax sugar* which typically results in a
-pair beginning with a specific rune.  A separate component called the *decoder*
-transforms such data into a rich set of value types.
+The parser recognizes various *syntax sugar* which abbreviates verbose syntax,
+and may result in special data structures (typically, a pair with a rune in its
+first, and payload in its second position) which another Zisp component called
+the *decoder* can transform into a rich set of value types.
+
+The most ubiquitous syntax sugar is the list, which abbreviates a sequence of
+tail-linked pairs, terminated with a special nil value represented as `()`:
+
+    (x)      ->  (x & ())
+
+    (x y)    ->  (x & (y & ()))
+
+    (x y z)  ->  (x & (y & (z & ())))
+
+The following are so-called *improper lists*, ending in a non-nil value:
+
+    (x y & z)    ->  (x & (y & z))
+
+    (x y z & t)  ->  (x & (y & (z & t)))
+
+More details about syntax sugar, and the decoder, are explained later.
 
 
 ## Character Encoding
@@ -99,7 +117,8 @@ datum.  In other words, a datum is a value that can be printed out as a byte
 sequence which the parser can turn back into an equivalent datum.
 
 A value that is not a datum may nevertheless be *encoded* into one, allowing it
-to have an external representation.  After parsing, it needs to be *decoded*.
+to have an external representation.  After parsing, it needs to be *decoded* to
+actually become the expected value.
 
 One may speak of an *external representation of a value* where the value is not
 itself a datum, but can be encoded as one.  The more strictly correct term for
@@ -115,23 +134,7 @@ As an example, the expression `#(x y z)` is an abbreviation for the equivalent
 after parsing, both will yield values that are indistinguishable in all but
 their memory address.
 
-The most ubiquitous syntax sugar is the list, which abbreviates a sequence of
-tail-linked pairs, terminated with a special nil value represented as `()`:
-
-    (x)      ->  (x & ())
-
-    (x y)    ->  (x & (y & ()))
-
-    (x y z)  ->  (x & (y & (z & ())))
-
-There are also so-called *improper lists* which are chains of pairs that end in
-a value other than nil:
-
-    (x y & z)    ->  (x & (y & z))
-
-    (x y z & t)  ->  (x & (y & (z & t)))
-
-An example of "syntax sugar" that is not a mere abbreviation is a quoted string
+An example of syntax sugar that is not a mere abbreviation is a quoted string
 which contains bytes that could not appear in a *bare* string:
 
     "foo bar"  ->  (#DQUOTE & <STRING>)