@@ -56,7 +56,7 @@ special form has the same syntax as a function call.
5656
5757The worst-case result of FLC is "DSL cancer." Every source file
5858is effectively written in its own domain-specific language. To
59−read a new file is to learn a new language -- "write-only code."
59+read a new file is to learn a new language—"write-only code."
6060
6161A fixed reserved-word set, especially with syntax highlighting,
6262and especially with orthogonal grammar (in C, you don't write
@@ -71,15 +71,19 @@ higher-order programming; write-only Hoon can certainly be
7171
7272# Design
7373
74−Because each twig stem has its own bulb, each has its own parser
75−rule. We'll describe these grammars as we go through the stems.
74+Hoon 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.
7680
7781But Hoon has a general syntax design with common principles and
7882regularities. We'll cover those here.
7983
8084## Glyphs and characters
8185
82−Hoon is a heavy punctuation user. To make ASCII great again,
86+Hoon is a heavy punctuation user. To aid pronunciation,
8387we've mapped each punctuation glyph to a syllable:
8488
8589```
@@ -133,17 +137,20 @@ implement both. All tall forms are regular.
133137Some twigs also have *irregular forms*, which follow no
134138principles at all. All irregular forms are flat.
135139
136−Some twigs (simple leafy ones) have *only* irregular forms.
140+Some twigs have *only* irregular forms.
137141
138142## Keywords versus runes
139143
140−A regular form starts with a *sigil*, which is either a
141−*keyword* or a *rune* -- at the programmer's choice.
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.
142149
143−A *keyword* is `:` and then the stem label - e.g., `:cons`.
150+A *keyword* is `:` and then the stem label—e.g., `:cons`.
144151
145−A *rune* is a pair of ASCII punctuation marks (a digraph) - e.g.,
146−`:-`. The first glyph in the rune indicates the category - e.g.,
152+A *rune* is a pair of ASCII punctuation marks (a digraph)—e.g.,
153+`:-`. The first glyph in the rune indicates the category—e.g.,
147154`:` runes make cells. Runes can be pronounced by their glyphs or
148155by their stem -- for `:-`, you can say either "colhep" or "cons".
149156
@@ -174,8 +181,10 @@ with the [original](../demo).
174181## Tall regular form
175182
176183Tall regular form starts with the sigil, followed by a `gap`
177−(any whitespace except `ace`), followed by a bulb whose twigs are
178−separated by `gap`.
184+(any whitespace except `ace`). After this is a
185+*[bulb](https://urbit.org/docs/about/glossary#bulb)*—the
186+contents of the twig—whose own twigs are separated by
187+`gap`.
179188
180189There are four body subtypes: *fixed*, *running*, *jogging*, and
181190*battery*. Stems with a *fixed* number of subexpressions
@@ -284,8 +293,11 @@ A *tall jogging* example (preceded by *1-fixed* `p`):
284293
285294### Conventions: *battery*
286295
287−A *battery* bulb is a list of symbol-twig pairs, for the battery
288−of a core. A conventional example:
296+A *battery* bulb is a list of symbol-twig pairs, for the
297+*[battery](https://urbit.org/docs/about/glossary#battery)*
298+of a
299+*[core](https://urbit.org/docs/about/glossary#core)*. A
300+conventional example:
289301
290302```
291303|%