Documentation ambiguity

[joshuareagan]

"A Hoon expression is called a twig. A twig is an AST node: the noun that the Hoon compiler makes when it parses a source expression."

This quotation is from twig.md. It's really puzzling. On the one hand, a "twig" is a Hoon expression, and Hoon expressions live in the source file. On the other hand, a "twig" is a node in a noun produced by the Hoon compiler when it's fed a source file.

I object to using the same word for both the input and the output of the compiler. Basically I'm following up on @belisarius222 's point in this thread:

https://github.com/urbit/docs/pull/205#issuecomment-334600935

If we want to talk about what the compiler does, even in this document, that's fine. I'm sure we could work out something that could be quite helpful. (I want to learn more about the compiler!) But we need to clarify our concepts because this sort of ambiguity leads to a lot of "double vision" for beginners. ("Does term X mean y or z? Or is Urbit somehow so radical that y = z?")

I'm calling for a decision about what to do with the word "twig". It seems like its true definition is the latter one: it's an AST node in a noun produced by the compiler. The word "expression" is well-worn but perfectly fine for describing the things we have in source files.

Of course I may be confused, in which case I'm happy to be corrected.

I recommend other ambiguities be noted in this issue, if there are any.

[cgyarvin]

Yes, “expression” for source and “twig” for node are fine.

Sent from my iPhone

On Oct 7, 2017, at 10:49 AM, Joshua Reagan notifications@github.com wrote:

Reopened urbit/docs#208.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[joshuareagan]

Huh, that was easy...

Next question: upon making the change above, how to clarify the names of sub-expressions? Some runes have certain sub-expressions that must evaluate to molds; the rest can evaluate to anything. The current docs call the former "moss" and the latter "seed". These names are said to be aliases for "twigs". In hoon.hoon it looks like everything is just called a "twig", so "moss" and "seed" seem to be docs-only vocabulary. Right now they're treated in a weird way in the rune docs, like aliases of ++twig mold within hoon.hoon. Of course they aren't really, so we're free to reserve these concepts for just the subexpressions if we want to.

I'm not really sure how much is gained by these names. Is there a possibility of conserving some weirdness points by eliminating them? It seems simpler and clearer to call normal sub-expressions (which can be anything) either just "subexpressions" or "expression child/children". Perhaps a special name is warranted for children that must evaluate to molds, in which case inertia and tradition may suffice for keeping the name "moss". But it's not a particularly intuitive name...

[joshuareagan]

Or maybe we can speak in terms of "moldy" and "woody" subexpressions, dropping "moss" and "seed"...

[joshuareagan]

I think my preference is simply to say "subexpression" but call the special ones "moldy".

[cgyarvin]

I have a better idea: “value” and “pattern” modes.

We’ve essentially gone from one mode and two syntaxes, to two modes (parsing contexts) and one syntax.

Sent from my iPhone

On Oct 7, 2017, at 8:10 PM, Joshua Reagan notifications@github.com wrote:

I think my preference is simply to say "subexpression" but call the special ones "moldy".

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[joshuareagan]

I deleted my old comments which were basically misunderstandings. I like the value/pattern distinction for expressions. With latest updates to Hoon and upcoming doc revisions, I'm happy.