From 7933e347666718a8ede4dae8d6bb74600bb1f970 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Wed, 10 Jul 2019 21:52:04 -0400
Subject: [PATCH] More on annotations

---
 preserves.md | 41 ++++++++++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 9 deletions(-)

diff --git a/preserves.md b/preserves.md
index 09dfd5f..1018dd5 100644
--- a/preserves.md
+++ b/preserves.md
@@ -336,7 +336,8 @@ value with `\x`.
 The second is as a sequence of pairs of hexadecimal digits interleaved
 with whitespace and surrounded by `#hex{` and `}`.
 
-       ByteString =/ %s"#hex{" *(ws / 2HEXDIG) ws "}"
+       ByteString =/ %s"#hex{" *(ws / hexchunk) ws "}"
+          hexchunk = 1*(2HEXDIG)
 
 The third is as a sequence of
 [Base64](https://tools.ietf.org/html/rfc4648) characters, interleaved
@@ -392,20 +393,25 @@ prefixing a `ByteString` containing the binary representation of the
 
 ### Annotations.
 
-When written down, a `Value` may have an associated sequence of
-*annotations* carrying “out-of-band” contextual metadata about the
-value. Each annotation is, in turn, a `Value`, and may itself have
-annotations.
+**Syntax.** When written down, a `Value` may have an associated
+sequence of *annotations* carrying “out-of-band” contextual metadata
+about the value. Each annotation is, in turn, a `Value`, and may
+itself have annotations.
 
             Value =/ ws "@" Value Value
 
 Each annotation is preceded by `@`; the underlying annotated value
 follows its annotations.
 
-Annotations appear within syntax denoting a `Value`; however, the
-annotations are not part of the denoted value. They are only part of
-the syntax. Annotations do not play a part in equivalences and
-orderings of `Value`s.
+Any chunk of hexadecimal digits in a `#hex{`...`}` `ByteString` may
+similarly be annotated.
+
+         hexchunk =/ ws "@" Value hexchunk
+
+**Equivalence.** Annotations appear within syntax denoting a `Value`;
+however, the annotations are not part of the denoted value. They are
+only part of the syntax. Annotations do not play a part in
+equivalences and orderings of `Value`s.
 
 Reflective tools such as debuggers, user interfaces, and message
 routers and relays---tools which process `Value`s generically---may
@@ -901,6 +907,23 @@ treat them specially.
   and one which enforces validity (i.e. side-conditions) when reading,
   writing, or constructing `Value`s.
 
+### Comments.
+
+`String` values used as annotations are conventionally interpreted as
+comments.
+
+    @"I am a comment for the Dictionary"
+    {
+      @"I am a comment for the key"
+      key: @"I am a comment for the value"
+           value
+    }
+
+    #hex{00010203
+         @"I am a comment for the next chunk of ByteString data"
+         04050607
+         08090A0B}
+
 ### MIME-type tagged binary data.
 
 Many internet protocols use