Adds suggested changes

_books/ion-1-1/src/text/e_expressions.md

@@ -10,14 +10,24 @@ Macro and module names follow the syntax rules for _identifier_ [symbol tokens](
 There may not be any whitespace from the start of the E-expression through to the end of the macro reference.
 
 Values in the E-expression body follow the same syntax as values in an [S-expression](values.md#s-expressions) body.
-E-expressions are not values, so they may not be annotated.
+E-expressions are not values, so they may not be annotated; to annotate the result of an e-expression use the 
+[`annotate`](../macros/system_macros.md#annotate) macro.
 
 ```ion
 (:pi)              // Invokes the macro 'pi'
 (:1)               // Invokes the macro with address 1 in the macro table
 (:constants::pi)   // Invokes the macro 'pi' from the module 'constants'
 
 (: pi)             // ERROR: whitespace is not permitted between '(:' and the macro reference
+foo::(:pi)         // ERROR: e-expression may not be annotated
+```
+
+E-expressions may also appear in structs in place of an entire name-value pair.
+```ion
+{
+  foo: 1,
+  (:bar 2), // Expands to a struct that is spliced into this struct
+}
 ```
 
 ### Expression Groups
@@ -27,7 +37,7 @@ To pass multiple arguments to a single macro parameter, the arguments to the par
 Inside an E-expression, an expression group starts with `(::`.
 The remainder of the expression group uses the same syntax as an [S-expression](values.md#s-expressions).
 Expression groups are not values, so they may not be annotated.
-Expression groups may not have another expression group as the direct 
+Expression groups may not contain another expression group.
 
 
 ```ion

_books/ion-1-1/src/text/encoding.md

@@ -1,10 +1,11 @@
 # Ion 1.1 Text Encoding
 
 The Ion text encoding is a stream of UTF-8 encoded text.
-It is intended to be easy to read and write by humans in any text-based application.
+It is intended to be easy to read and write by humans.
 
-Whitespace is insignificant and is only required where necessary to separate tokens, and C-style comments 
-(either block or in-line) are treated as whitespace (and are not part of the binary encoding).
+Whitespace is insignificant and is only required where necessary to separate tokens.
+C-style comments (either block or in-line) are treated as whitespace;
+they are not part of the data model and implementations are not required to preserve them.
 
 A text Ion 1.1 stream begins with the Ion 1.1 [version marker](../todo.md) (`$ion_1_1`) followed by a series of
 [value literals](values.md) and/or [encoding expressions](e_expressions.md).

_books/ion-1-1/src/text/values.md

@@ -15,6 +15,8 @@ jpeg :: {{ ... }}                        // Indicates the blob contains jpeg dat
 bool :: null.int                         // A very misleading annotation on the integer null
 '' :: 1                                  // An empty annotation
 null.symbol :: 1                         // ERROR: type annotation cannot be null 
+foo::(:make_string "a" "b")              // ERROR: e-expressions may not be annotated
+(:make_string foo::(:: "a" "b"))         // ERROR: expression groups may not be annotated
 ```
 
 ## Nulls
@@ -84,7 +86,7 @@ A binary-encoded `int` consists of `0b` followed by one or more base 2 digits (`
 A hexadecimal-encoded `int` consists of `0x` followed by one or more case-insensitive base 16 digits (`0123456789abcdefABCDEF`).
 
 All integer values may be preceded by an optional minus sign (`-`), indicating that the value is negative.
-(The token `-0` is legal and equivalent to `0`.)
+(The token `-0` is legal and equivalent to `0`; to distinguish `-0` from `0`, consider encoding as a `decimal` or `float` instead.)
 Single underscores may be used to separate digits; consecutive underscores are never allowed.
 All integer values must be followed by one of the fifteen numeric stop-characters: `{}[](),\"\'\ \t\n\r\v\f`.
 
@@ -147,7 +149,7 @@ When encoding a `float` value to Ion text, an implementation MAY want to conside
 
 
 #### Examples
-Although the textual representative of `1.2e0` itself is irrational, its
+Although the textual representation of `1.2e0` itself is irrational, its
 canonical form in the data model is not (based on the rounding rules), thus
 the following text forms all map to the same `float` value:
 
@@ -263,7 +265,8 @@ In the text format, timestamps follow the [W3C note on date and time formats](ht
 but they must end with the literal `T` if not at least whole-day precision.
 Fractional seconds are allowed, with at least one digit of precision and an unlimited maximum.
 Local-time offsets may be represented as either hour:minute offsets from UTC, or as the literal `Z` to denote a local time of UTC.
-They are required on timestamps with time and are not allowed on date values.
+If the offset is `-00:00`, it indicates that the local offset in which the timestamp was recorded is unknown, and that the time is therefore encoded as UTC.
+Local-time offsets are required on timestamps with time and are not allowed on date values.
 
 ```ion
 2007-02-23T12:14Z                // Seconds are optional, but local offset is not