@@ -119,37 +119,42 @@ pairs). We pronounce runes using their glyph names—for `:-`,
119119we say "colhep".
120120
121121Each rune is followed by one or more subexpressions. The number and
122−kind of subexpressions depend on the rune used.
122+kind of subexpressions depend on which rune is used.
123123
124124```
125125:- 25
1261263
127127```
128128
129−This twig uses `:-` to produce a cell: `[25 3]`. There are always two
130−subexpressions following the `:-` in syntactically correct Hoon code,
131−the first of which, when evaluated, becomes the *head* (i.e., the left)
132−and the second of which becomes the *tail* (i.e., the right).
129+The `:-` rune is always followed by two 'value' subexpressions to
130+produce a cell: `[25 3]`. The first subexpression, when evaluated,
131+becomes the *head* (i.e., the left) of the cell, and the second
132+becomes the *tail* (i.e., the right).
133133
134−Hoon expressions are sometimes called
135−[twigs](https://urbit.org/docs/about/glossary#twig). You'll find that
136−Hoon code has a tree-like structure, so you can think of the various
137−expressions as twigs of the tree. The subexpressions following the
138−rune are sometimes called the *children* of that twig.
134+There are two kinds of expressions in Hoon: *value* and *pattern*.
135+Value expressions evaluate to any sort of data. They can be as simple
136+as `25`, or they may require more computation, as in `(add 22 3)`. The
137+`:-` expression above is itself a value expression, as are the vast
138+majority of Hoon expressions.
139139
140−## Tall and flat forms
140+A pattern expression must be a *mold*, which we'll explain a bit
141+[later](https://urbit.org/docs/hoon/basic).
141142
142−There are two kinds of Hoon expression syntax: *tall* and *flat*.
143−Most runes can be used in both tall and flat twigs. Tall twigs can
144−contain flat twigs, but not vice versa.
143+## Tall and flat styles
145144
146−The `:-` expression in the last subsection was in tall form. Here's
145+There are two styles of Hoon expression syntax: *tall* and *flat*.
146+Most runes can be used in both tall and flat styles. Tall expressions
147+are (typically) multi-line, but flat expressions must not have line
148+breaks in them. Tall expressions may contain flat ones, but not vice
149+versa.
150+
151+The `:-` expression in the last subsection was in tall style. Here's
147152the flat equivalent:
148153
149154`:-(25 3)`
150155
151−Visually, a tall twig looks like a "statement" and a flat twig
152−like an "expression," preserving the attractive visual shape of
156+Visually, the tall style looks more "statement"-like and flat-style
157+looks "expression"-like, preserving the attractive visual shape of
153158procedural code without the nasty side effects.
154159
155160## Regular and irregular forms
@@ -159,7 +164,7 @@ There is a regular flat form and a regular tall form; most runes
159164have both kinds of implementation. All tall forms are regular.
160165
161166Some runes also have *irregular forms*, which follow no
162−principles at all. All irregular forms are flat.
167+general principles at all. All irregular forms are flat.
163168
164169```
165170.= 22
@@ -172,52 +177,51 @@ follow, and returns a boolean. Above is the tall, regular form of
172177
173178`=(22 23)`
174179
175−Some twigs have *only* irregular forms.
180+Some kinds of expression have *only* irregular forms.
176181
177182## Tall regular form
178183
179184Tall regular forms start with a rune followed by a `gap`.
180−(Remember, a `gap` is any whitespace other than `ace`.) After
181−that are the number and types of subexpressions appropriate for
182−that rune. Each subexpression is separated from its neighboring
183−subexpressions by a `gap`.
185+(Remember, a `gap` is any whitespace other than `ace`, or a line
186+break.) After that are the number and types of subexpressions
187+appropriate for that rune. Each subexpression is separated from
188+its neighboring subexpressions by a `gap`.
184189
185−Let's call everything in the twig after the initial rune the twig
186−*body*. There are four body subtypes: *fixed*, *running*, *jogging*,
190+Everything after the initial rune in an expression is called the
191+*body*. There are four body types: *fixed*, *running*, *jogging*,
187192and *[battery](https://urbit.org/docs/about/glossary#battery)*.
188193
189194Runes with a *fixed* number of subexpressions self-terminate. For
190195instance, the `:-` and `.=` runes each have two subexpressions
191−and are self-terminating. Otherwise the twig is terminated by both
192−a `gap`, then either `==` (*running* or *jogging*, most twigs) or
193−`--` (*battery*).
196+and are self-terminating. Otherwise the body is terminated by a
197+`gap` followed by either `==` (*running* or *jogging*, most runes)
198+or `--` (*battery*).
194199
195−The *running* body has a list of *children* (i.e., subexpressions).
196−The *jogging* body has a list of child pairs, where the members of
200+The *running* body is a list of *children* (i.e., subexpressions).
201+The *jogging* body is a list of child pairs, where the members of
197202each pair are separated by a `gap`. The *battery* body is
198−a list of symbol-child pairs, separated by a gap, prefixed by `++`
199−and then a gap.
203+a list of symbol-child pairs, each separated by a `gap`. See below
204+for examples of each body type.
200205
201206This definition is enough to write Hoon that will parse. But
202207writing code with optimal whitespace management requires some
203208additional informal conventions.
204209
205210Whitespace design in Hoon is an art, not a science. It involves
206−both tall/flat mode switches and well-shaped gaps. (Hoon layout
211+both tall/flat style switches and well-shaped gaps. (Hoon layout
207212could probably be done automatically with reasonable quality.
208213But it would at least take machine learning, not a rule engine.)
209214
210215There are only two real *rules* in Hoon whitespace design: don't
211216go past 80 characters, and don't use (completely) blank lines.
212−Otherwise, if it looks good and is easy to read, it's good. The
217+Otherwise, if it looks good and is easy to read, it's fine. The
213218best way to learn the art is to do everything by convention
214219until you know what you're doing. Here are the conventions:
215220
216221### Conventions: *fixed*
217222
218−Twig bodies with *fixed* fanout use "backstep" indentation, which
219−slopes backward and to the right by two spaces per line. The first
220−twig child is two spaces after the end of the rune.
223+Expressions with *fixed* bodies use "backstep" indentation, which
224+slopes backward and to the right by two spaces per line.
221225
222226Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:
223227
@@ -238,14 +242,15 @@ r
238242s
239243```
240244
241−In optimal usage of backstep indentation, the most complicated twigs
242−are at the bottom, keeping code flow vertical rather than diagonal.
245+In optimal usage of backstep indentation, the most complicated
246+expressions are at the bottom, keeping code flow vertical rather than
247+diagonal.
243248
244249### Conventions: *running*
245250
246−A *running* twig body (a simple child list) puts the first child two
247−spaces after the end of the rune, and the following children straight
248−down:
251+A *running* body (a simple child list of arbitrary length) puts the
252+first child two spaces after the end of the rune, and the following
253+children straight down:
249254
250255A *running* example:
251256
@@ -260,10 +265,10 @@ A *running* example:
260265
261266### Conventions: *jogging*
262267
263−A *jogging* twig body (a list of child pairs) is like a running
264−body, but with a pair of children on each line, separated by
268+A *jogging* body (a list of child pairs of arbitrary length) is like
269+a running body, but with a pair of children on each line separated by
265270two spaces. Most jogging bodies start with a *fixed* sequence;
266−the first jogging pair is below and two steps backward from the
271+the first pair is below and two steps backward from the
267272last fixed child.
268273
269274There are two jogging conventions: *flat* (pair on one line) and
@@ -315,10 +320,10 @@ conventional example:
315320
316321Flat regular form starts with the rune, followed by `pal`, `(`
317322(left parenthesis), followed by a body whose subexpressions
318−are separated by `ace` (one space), followed by `par`, `)` (right
319−parenthesis).
323+are all separated by `ace`s (single spaces), followed by `par`,
324+`)` (right parenthesis).
320325
321−A twig in flat form, `:if`, `?:`, `{$if p/twig q/twig r/twig}`:
326+A expression in flat form, `?:`, which is 3-fixed:
322327
323328`?:(p q r)`
324329