@@ -47,10 +47,10 @@ shaped more or less like procedural programs.
4747
4848## Feature/label confusion
4949
50−*Feature/label confusion* (FLC) is any syntax which makes it hard
51−for the eye to tell whether a token on the screen is a feature of
52−the language, or a label in the program. For example, in Lisp a
53−special form has the same syntax as a function call.
50+*Feature/label confusion* (FLC) is the result of any syntax that
51+makes it hard for the eye to tell whether a token on the screen is
52+a feature of the language, or a label in the program. For example,
53+in Lisp a special form has the same syntax as a function call.
5454
5555The worst-case result of FLC is "DSL cancer." Every source file
5656is effectively written in its own domain-specific language. To
@@ -101,8 +101,8 @@ aloud or silently, than "left paren".
101101Note that the list includes two separate whitespace forms: `ace`
102102for a single space; `gap` is either 2+ spaces or a newline. In Hoon,
103103the only significance in whitespace is the difference between
104−`ace` and `gap`. Comments start with `::` and run to the end of
105−the line.
104+`ace` and `gap`. Comments also count as `gap` whitespace—they
105+start with `::` and run to the end of the line.
106106
107107An 80-column right margin is strongly encouraged. Really
108108well-groomed Hoon uses a 55-column code margin and puts a standard
@@ -119,7 +119,7 @@ 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.
122+kind of subexpressions depend on the rune used.
123123
124124```
125125:- 25
@@ -134,7 +134,7 @@ and the second of which becomes the *tail* (i.e., the right).
134134Hoon expressions are sometimes called
135135[twigs](https://urbit.org/docs/about/glossary#twig). You'll find that
136136Hoon code has a tree-like structure, so you can think of the various
137−expressions as twigs of this tree. The subexpressions following the
137+expressions as twigs of the tree. The subexpressions following the
138138rune are sometimes called the *children* of that twig.
139139
140140## Tall and flat forms
@@ -176,15 +176,15 @@ Some twigs have *only* irregular forms.
176176
177177## Tall regular form
178178
179−Tall regular form starts with the rune, followed by a `gap`.
180−(Remember, a `gap` is any whitespace other than `ace`.). After
179+Tall regular forms start with a rune followed by a `gap`.
180+(Remember, a `gap` is any whitespace other than `ace`.) After
181181that are the number and types of subexpressions appropriate for
182−that rune. Each subexpression is separated from the others by a
183−`gap`.
182+that rune. Each subexpression is separated from its neighboring
183+subexpressions by a `gap`.
184184
185185Let's call everything in the twig after the initial rune the twig
186186*body*. There are four body subtypes: *fixed*, *running*, *jogging*,
187−and [battery](https://urbit.org/docs/about/glossary#battery).
187+and *[battery](https://urbit.org/docs/about/glossary#battery)*.
188188
189189Runes with a *fixed* number of subexpressions self-terminate. For
190190instance, the `:-` and `.=` runes each have two subexpressions
@@ -194,12 +194,13 @@ a `gap`, then either `==` (*running* or *jogging*, most twigs) or
194194
195195The *running* body has a list of *children* (i.e., subexpressions).
196196The *jogging* body has a list of child pairs, where the members of
197−each pair is separated by a `gap`. The *battery* body is
197+each pair are separated by a `gap`. The *battery* body is
198198a list of symbol-child pairs, separated by a gap, prefixed by `++`
199199and then a gap.
200200
201−This definition is enough to write Hoon that will parse. But the
202−proper shape of the whitespace gaps requires an informal convention.
201+This definition is enough to write Hoon that will parse. But
202+writing code with optimal whitespace management requires some
203+additional informal conventions.
203204
204205Whitespace design in Hoon is an art, not a science. It involves
205206both tall/flat mode switches and well-shaped gaps. (Hoon layout
@@ -334,7 +335,7 @@ There is no flat regular form for *battery* bodies. Be tall.
334335
335336Hoon does not enforce any rule on symbols, except that capitals
336337are not allowed (use kebab-case). However, a lot of system code
337−is written in using "lapidary" conventions that need explanation.
338+is written using "lapidary" conventions that need explanation.
338339
339340Naming things is one of the hard problems in CS. Dodging this
340341problem is one of the reasons mathematicians use Greek letters,