@@ -80,39 +80,35 @@ it's still fun and useful to [learn more](../../nock).
8080### <a name="hoon">`hoon`</a> (AST node)
8181
8282A [`hoon`](../reference) is the result of parsing a Hoon source
83−expression into an AST node. Because every Hoon program is,
84−in its entirety, a single expression of Hoon, the result of parsing
85−a whole Hoon program into an AST is a single `hoon`.
83+expression into an AST node. These AST nodes are nouns, like all
84+other Hoon data. Because every Hoon program is, in its entirety, a
85+single expression of Hoon, the result of parsing the whole thing
86+into an AST is a single `hoon`.
8687
87−As the noun that the parser produces, a hoon is a tagged union of
88−the form `[tag data]`, where the tag is a constant such as `%brts`,
89−which is matched up with the appropriate type of data (often more
90−`hoon`s). For example, the expression `:-(p q)`, once parsed into
91−an AST, becomes the tagged union:
92−
93−```
94−[%clhp p=hoon q=hoon]
95−```
96−
97−The `%clhp` is for "colhep". Keep in mind that `p` and `q` would be
98−parsed too. So if `p` is 2 and `q` is 17, the parsed result is:
88+A hoon is a tagged union of the form `[%tag data]`, where the tag
89+is a constant such as `%brts` (from the source `|=`, i.e. "bartis"),
90+and is matched up with the appropriate type of data (often more
91+`hoon`s, from source subexpressions). For example, the expression
92+`:-(2 17)`, once parsed into an AST, becomes the following:
9993
10094```
10195[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
10296```
10397
104−The 2 and 17 have each been parsed as `%sand`-tagged `hoon`s, which
105−represent constant atoms. To parse Hoon source into a hoon AST, use
106−`ream` on a `cord`, e.g.:
98+The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and
99+17 have each been parsed as `%sand`-tagged hoons, which represent
100+atoms (in this case each with an aura of `%ud`, i.e. unsigned
101+decimal). To parse Hoon source into a hoon AST, use `ream` on a `cord`
102+containing Hoon source, e.g.:
107103
108104```
109−(ream ':-(2 17)')
105+(ream ':+(12 7 %a)')
110106```
111107
112−Try it in the `:dojo` to get:
108+Try the above in the `:dojo` to get:
113109
114110```
115−[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
111+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
116112```
117113
118114### <a name="mint">`mint`</a> (compiler)
@@ -120,14 +116,19 @@ Try it in the `:dojo` to get:
120116[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]`
121117to a cell `[type nock]`, where a [`type`](#type) is type
122118information, a [`hoon`](#hoon) is a parsed expression (AST), and a
123−`nock` is a Nock formula. `mint` accepts a subject type and a parsed
119+`nock` is a Nock formula. `mint` accepts a type and a parsed
124120source expression; it produces a product type and an executable
125121formula.
126122
127−Calculating the output type from the input type and the source
128−code is called "type inference". If you've used another typed
129−functional language, like Haskell, Hoon's type inference does the
130−same job but with less intelligence.
123+As part of the type-checking process, mint checks that the output
124+type "nests" within the input type, i.e. that the output type is a
125+subset of the input type. If not, mint halts with a `nest-fail`
126+crash.
127+
128+Calculating the output type from the input `hoon` is called "type
129+inference". If you've used another typed functional language, like
130+Haskell, Hoon's type inference does the same job but with less
131+intelligence.
131132
132133Haskell infers backward and forward; Hoon only infers forward.
133134Hoon can't figure out the type of a noun from how you use it,
@@ -139,15 +140,15 @@ which makes your program more readable anyway. Also, the dumber
139140the compiler, the easier it is for a dumb human to understand
140141what the compiler is thinking.
141142
142−To compile the hoon from the last subsection into Nock, try the
143−following in `:dojo`:
143+To compile an example `hoon` from the last subsection into Nock,
144+try the following in `:dojo`:
144145
145146```
146147(mint:ut %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])
147148```
148149
149−The `%noun` is for the data type of the subject, and the tagged
150−union after that is the hoon.
150+The `%noun` is the input `type` for `mint`, and the tree after that
151+is the input `hoon`.
151152
152153### <a name="type">`type`</a> (type, as range)
153154
@@ -158,7 +159,7 @@ types; they are always defined by inference (i.e., by
158159
159160All types are assembled out of base types defined in `++type`.
160161(Look up `++ type` in hoon.hoon for examples.) When the compiler
161−does type-inference on a prorgam, it assembles complex types out
162+does type-inference on a program, it assembles complex types out
162163of the simpler built-in types.
163164
164165### `gate` (function)
@@ -181,7 +182,7 @@ A gate is a special case of a core: a core with one arm, whose
181182name is the empty string. The shape of a core is `[battery
182183payload]`, where *battery* is a tree of Nock formulas
183184
184−### `mold` (type, as constructor)
185+### `mold` (constructor)
185186
186187A `mold` is a constructor function (`gate`). Its sample is any
187188noun; its product is a structured noun. A mold is idempotent;
@@ -194,14 +195,15 @@ to validate untrusted network input.
194195### `face` (named variable)
195196
196197In a conventional language, we have a scope, environment or
197−symbol table. Declaring a variable, like `var foo: atom`, adds
198−the name `foo` to the table with type `atom`.
199−
200−The Hoon analogue is `=|(foo atom)`. But Hoon has a
201−homoiconic heap; there is no inscrutable scope or environment.
202−There is just the subject, which is one noun. To "declare a
203−variable" is to make a cell `[variable old-subject]`, and use that
204−as the subject of the next expression.
198+symbol table. Declaring a variable, like e.g. `int foo = 3`,
199+adds the name `foo` to the table with type `int`.
200+
201+The Hoon analogue is `=/(foo atom 3 ...)`, where `foo` is a `face`
202+and `atom` is the type. But Hoon has a homoiconic heap; there is no
203+inscrutable scope or environment. There is just the subject, which
204+is one noun. To "declare a variable" is to make a cell
205+`[variable old-subject]`, and use thatas the subject of the next
206+expression.
205207
206208The label `foo` isn't a key in a symbol table; it's stored as a kind
207209of metadata, in the type ([`type`](#type)) of the new value. It's not