comments on spec and a few other things
Change-Id: I154e452946209a158a8b6fbfb7579801a8186879
diff --git a/doc/tutorial/basics/aliases.md b/doc/tutorial/basics/aliases.md
index def895e..481294c 100644
--- a/doc/tutorial/basics/aliases.md
+++ b/doc/tutorial/basics/aliases.md
@@ -8,13 +8,12 @@
A typical use case is to provide access to a shadowed field.
-Alias are not members of a struct and thus are not part of the model and
-cannot be accessed.
-
+Alias are not members of a struct. They can be referred to, but they do not
+appear in the output.
<!-- CUE editor -->
```
-A = a // A is an alias to a
+A = a // A is an alias for a
a: {
d: 3
}
diff --git a/doc/tutorial/basics/bottom.md b/doc/tutorial/basics/bottom.md
index 77be74b..8e1bf02 100644
--- a/doc/tutorial/basics/bottom.md
+++ b/doc/tutorial/basics/bottom.md
@@ -12,7 +12,7 @@
Logically all errors are equal, although errors may be associated with
metadata such as an error message.
-Note that an error is different from `null`: `null` is a valid JSON value,
+Note that an error is different from `null`: `null` is a valid value,
whereas `_|_` is not.
<!-- CUE editor -->
@@ -33,4 +33,4 @@
l: _|_
list: [0, 1, 2]
val: _|_
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/bytes.md b/doc/tutorial/basics/bytes.md
index 77341a2..ce11d7f 100644
--- a/doc/tutorial/basics/bytes.md
+++ b/doc/tutorial/basics/bytes.md
@@ -11,7 +11,7 @@
\xnn // arbitrary byte value defined as a 2-digit hexadecimal number
\0nnn // arbitrary byte value defined as a 3-digit octal number
-
+<!-- jba: this contradicts the spec, which has \nnn (no leading zero) -->
<!-- CUE editor -->
```
diff --git a/doc/tutorial/basics/coalesce.md b/doc/tutorial/basics/coalesce.md
index 3a487a0..082708a 100644
--- a/doc/tutorial/basics/coalesce.md
+++ b/doc/tutorial/basics/coalesce.md
@@ -4,6 +4,15 @@
# Null Coalescing
+<!-- jba: the terms here are confusing. "Null coalescing" is actually not
+ that, but then there is something called "actual null coalescing."
+
+ Just say that because _|_ | X evaluates to X, you can use disjunction
+ to represent fallback values.
+
+ And then you can use that to effectively type-check with a default value.
+-->
+
With null coalescing we really mean error, or bottom, coalescing.
The defaults mechanism for disjunctions can also be
used to provide fallback values in case an expression evaluates to bottom.
@@ -35,4 +44,4 @@
b: "None"
n: [null]
v: "default"
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/emit.md b/doc/tutorial/basics/emit.md
index 7c8dd6e..03e25bf 100644
--- a/doc/tutorial/basics/emit.md
+++ b/doc/tutorial/basics/emit.md
@@ -6,6 +6,10 @@
By default all top-level fields are emitted when evaluating a configuration.
CUE files may define a top-level value that is emitted instead.
+<!-- jba:
+It's unclear how they do that. Is it the first form in the file?
+And this is not in the spec AFAICT.
+-->
Values within the emit value may refer to fields defined outside of it.
@@ -28,4 +32,4 @@
```
a: 1
b: 2
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/hidden.md b/doc/tutorial/basics/hidden.md
index e57f3b7..03cea5e 100644
--- a/doc/tutorial/basics/hidden.md
+++ b/doc/tutorial/basics/hidden.md
@@ -9,7 +9,7 @@
To includes fields in the configuration that start with an underscore
put them in quotes.
-Quoted an non-quoted fields share the same namespace unless they start
+Quoted and non-quoted fields share the same namespace unless they start
with an underscore.
<!-- CUE editor -->
@@ -23,4 +23,4 @@
```
"_foo": 2
foo: 4
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/ranges.md b/doc/tutorial/basics/ranges.md
index c37ea75..ab796a6 100644
--- a/doc/tutorial/basics/ranges.md
+++ b/doc/tutorial/basics/ranges.md
@@ -35,8 +35,8 @@
```
a: 3.5
b: _|_
-c: 3
+c: 3 <!-- jba: this should be 3.0, right? -->
d: "ma"
e: _|_
r1: 3..7
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/templates.md b/doc/tutorial/basics/templates.md
index d0d25ec..3748cdb 100644
--- a/doc/tutorial/basics/templates.md
+++ b/doc/tutorial/basics/templates.md
@@ -4,6 +4,8 @@
# Templates
+<!-- jba: this is not in the spec, aside from the TemplateLabel grammar rule. -->
+
One of CUE's most powerful features is templates.
A template defines a value to be unified which each field of a struct.
@@ -41,4 +43,4 @@
command: "nginx"
}
}
-```
\ No newline at end of file
+```
