@@ -72,13 +72,22 @@ higher-order programming; write-only Hoon can certainly be
7272# Design
7373
7474Hoon expressions are called
75−*[twigs](https://urbit.org/docs/about/glossary#twig)*. The name
76−of a twig is its
77−*[stem](https://urbit.org/docs/about/glossary#stem)*. Because
78−each twig stem has its own structure, each has its own parser
79−rule. We'll describe these grammars as we go through the stems.
80−
81−But Hoon has a general syntax design with common principles and
75+*[twigs](https://urbit.org/docs/about/glossary#twig)*, and at the
76+beginning of each twig is a
77+*[rune](https://urbit.org/docs/about/glossary#rune)*. Each rune
78+type has a name, called a
79+*[stem](https://urbit.org/docs/about/glossary#stem)*. Finally,
80+each stem has its own structure, e.g.:
81+
82+> :-
83+> (add 12 13)
84+> (sub 10 7)
85+
86+This twig uses the rune `:-` (stem: `cons`) to produce an ordered
87+pair: `[25 3]`. There are two subexpressions following the `:-`,
88+corresponding to the two parts of the `cons` structure.
89+
90+Hoon has a general syntax design with common principles and
8291regularities. We'll cover those here.
8392
8493## Glyphs and characters
@@ -139,48 +148,19 @@ principles at all. All irregular forms are flat.
139148
140149Some twigs have *only* irregular forms.
141150
142−## Keywords versus runes
143−
144−A regular form starts with a
145−*[sigil](https://urbit.org/docs/about/glossary#sigil)*, which is
146−either a *keyword* or a
147−*[rune](https://urbit.org/docs/about/glossary#rune)*—at
148−the programmer's choice.
151+## Runes
149152
150−A *keyword* is `:` and then the stem label—e.g., `:cons`.
153+As mentioned earlier, a regular form starts with a
154+*[rune](https://urbit.org/docs/about/glossary#rune).
151155
152156A *rune* is a pair of ASCII punctuation marks (a digraph)—e.g.,
153157`:-`. The first glyph in the rune indicates the category—e.g.,
154158`:` runes make cells. Runes can be pronounced by their glyphs or
155−by their stem -- for `:-`, you can say either "colhep" or "cons".
156−
157−Keywords may be less challenging for early learners. Rune style
158−is less cluttered and distracting for experienced programmers;
159−the system codebase is all in rune style. Beginners can start
160−with keywords and move to runes; start with runes and stick
161−with runes; or start with keywords and stick with keywords.
162−
163−Here's the FizzBuzz demo code, in idiomatic rune syntax. Compare
164−with the [original](../demo).
165−
166−```
167− |= end/atom
168− =/ count 1
169− |- ^- (list tape)
170− ?: =(end count) ~
171− :_ $(count (add 1 count))
172− ?: =(0 (mod count 15))
173− "FizzBuzz"
174− ?: =(0 (mod count 5))
175− "Fizz"
176− ?: =(0 (mod count 3))
177− "Buzz"
178− (pave !>(count))
179−```
159+by their stem—for `:-`, you can say either "colhep" or "cons".
180160
181161## Tall regular form
182162
183−Tall regular form starts with the sigil, followed by a `gap`
163+Tall regular form starts with the rune, followed by a `gap`
184164(any whitespace except `ace`). After this is a
185165*[bulb](https://urbit.org/docs/about/glossary#bulb)*—the
186166contents of the twig—whose own twigs are separated by
@@ -188,7 +168,7 @@ contents of the twig—whose own twigs are separated by
188168
189169There are four body subtypes: *fixed*, *running*, *jogging*, and
190170*battery*. Stems with a *fixed* number of subexpressions
191−self-terminate. For instance, `:if` has three subexpressions and
171+self-terminate. For instance, `?:` has three subexpressions and
192172is self-terminating. Otherwise the twig is terminated by a
193173`gap`, then either `==` (*running* or *jogging*, most twigs) or
194174`--` (*battery*).
@@ -312,7 +292,7 @@ conventional example:
312292
313293## Flat regular form
314294
315−Flat regular form starts with the sigil, followed by `pal`
295+Flat regular form starts with the rune, followed by `pal`
316296(`(`, left parenthesis), followed by a bulb whose subexpressions
317297are separated by `ace` (one space), followed by `par` (`)`, right
318298parenthesis).