Update Ion 1.1 spec with feedback from final comment period (#390)

Author: popematt

_books/ion-1-1/src/SUMMARY.md

@@ -36,8 +36,8 @@
         * [timestamp](binary/values/timestamp.md)
         * [string](binary/values/string.md)
         * [symbol](binary/values/symbol.md)
-        * [blob](binary/values/lob.md)
-        * [clob](binary/values/lob.md)
+        * [blob](binary/values/blob.md)
+        * [clob](binary/values/clob.md)
         * [list](binary/values/list.md)
         * [sexp](binary/values/sexp.md)
         * [struct](binary/values/struct.md)

_books/ion-1-1/src/binary/values/blob.md

@@ -0,0 +1,23 @@
+## Blobs
+
+Opcode `FE` indicates a blob of binary data. A `FlexUInt` follows that represents the blob's byte-length.
+
+`0xEB x07` represents `null.blob`.
+
+### Example `blob` encoding
+```
+┌──── Opcode FE indicates a blob, FlexUInt length follows
+│   ┌─── Length: FlexUInt 24
+│   │
+FE 31 49 20 61 70 70 6c 61 75 64 20 79 6f 75 72 20 63 75 72 69 6f 73 69 74 79
+      └────────────────────────────────┬────────────────────────────────────┘
+                            24 bytes of binary data
+```
+
+### Encoding of `null.blob`
+```
+┌──── Opcode 0xEB indicates a typed null; a byte follows specifying the type
+│  ┌─── Null type: blob
+│  │
+EB 07
+```

_books/ion-1-1/src/binary/values/clob.md

@@ -0,0 +1,24 @@
+## Clobs
+
+Opcode `FF` indicates a clob--binary character data of an unspecified encoding. A `FlexUInt` follows that represents
+the clob's byte-length.
+
+`0xEB x08` represents `null.clob`.
+
+### Example `clob` encoding
+```
+┌──── Opcode FF indicates a clob, FlexUInt length follows
+│   ┌─── Length: FlexUInt 24
+│   │
+FF 31 49 20 61 70 70 6c 61 75 64 20 79 6f 75 72 20 63 75 72 69 6f 73 69 74 79
+      └────────────────────────────────┬────────────────────────────────────┘
+                            24 bytes of binary data
+```
+
+### Encoding of `null.clob`
+```
+┌──── Opcode 0xEB indicates a typed null; a byte follows specifying the type
+│  ┌─── Null type: clob
+│  │
+EB 08
+```

_books/ion-1-1/src/binary/values/lob.md

@@ -27,7 +27,7 @@ encoding-directive ::= '$ion::(encoding ' module-name* ')'
 
 ### Modules
 ```bnf
-module-body             ::= import* inner-module* symbol-table? macro-table?
+module-body             ::= import* inner-module* macro-table? symbol-table? 
 
 shared-module           ::= '$ion_shared_module::' ivm '::(' catalog-key module-body ')'
 
@@ -43,15 +43,15 @@ inner-module            ::= '(module' module-name module-body ')'
 
 module-name             ::= unannotated-identifier-symbol
 
-symbol-table            ::= '(symbol_table' symbol-table-entry* ')'
+symbol-table            ::= '(symbols' symbol-table-entry* ')'
 
 symbol-table-entry      ::= module-name | symbol-list
 
 symbol-list             ::= '[' symbol-text* ']'
 
 symbol-text             ::= symbol | string
 
-macro-table             ::= '(macro_table' macro-table-entry* ')'
+macro-table             ::= '(macros' macro-table-entry* ')'
 
 macro-table-entry       ::= macro-definition
                           | macro-export

_books/ion-1-1/src/grammar.md

@@ -1,6 +1,6 @@
 # Defining macros
 
-A macro is defined using a `macro` clause within a [module](../modules.md)'s [`macro_table` clause](../modules.md#macro_table).
+A macro is defined using a `macro` clause within a [module](../modules.md)'s [`macros` clause](../modules.md#macros).
 
 ## Syntax
 ```ion
@@ -204,7 +204,7 @@ When they are invoked, they expand to a stream of a single value: the Ion scalar
 ```ion
 $ion::
 (module _
-  (macro_table
+  (macros
     (macro greeting () "hello")
     (macro birthday () 1996-10-11)
     // Annotations are also literal
@@ -262,7 +262,7 @@ expression-group   ::= '(..' expression* ')'
 ```ion
 $ion::
 (module _
-  (macro_table
+  (macros
     // Calls the system macro `values`, allowing it to produce a stream of three values.
     (macro nephews () (.values Huey Dewey Louie))
 
@@ -283,7 +283,7 @@ $ion::
 > ```ion
 > $ion::
 > (module _
->   (macro_table
+>   (macros
 >     (macro list_of_nephews () [(.nephews)])
 >     //                          ^^^^^^^^
 >     // ERROR: Calls a macro that has not yet been defined in this module.
@@ -311,7 +311,7 @@ variable-name      ::= ion-identifier
 ```ion
 $ion::
 (module _
-  (macro_table
+  (macros
     // Produces a stream that repeats the content of parameter `x` twice.
     (macro twice (x*) (.values (%x) (%x)))
   )
@@ -342,7 +342,7 @@ If the expansion was empty, no values are spliced into the container.
 ```ion
 $ion::
 (module _
-  (macro_table
+  (macros
     (macro bookend_list (x y*) [(%x), (%y), (%x)])
     (macro bookend_sexp (x y*) ((%x) (%y) (%x)))
   )
@@ -366,7 +366,7 @@ If the expansion was empty, no fields are spliced into the parent struct.
 ```ion
 $ion::
 (module _
-  (macro_table
+  (macros
     (macro resident (id names*)
         {
             town: "Riverside",

_books/ion-1-1/src/macros/defining_macros.md

@@ -264,7 +264,7 @@ Embedded text example:
 (:parse_ion
     '''
     $ion_1_1
-    $ion::(module _ (symbol_table ["foo" "bar"]]))
+    $ion::(module _ (symbols ["foo" "bar"]]))
     $1 $2
     '''
 )