opened
joshuareagan
username_0
"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.
Documentation ambiguity
issue
closed
joshuareagan
username_0
issue
reopened
joshuareagan
username_0
"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.
Documentation ambiguity
issue
created
cgyarvin
username_1
Yes, “expression” for source and “twig” for node are fine.

Sent from my iPhone

>
comment
created
joshuareagan
username_0
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 are also 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...
comment
created
joshuareagan
username_0
Or maybe we can speak in terms of "moldy" and "woody" subexpressions, dropping "moss" and "seed"...
comment
created
joshuareagan
username_0
I think my preference is simply to say "subexpression" but call the special ones "moldy".
comment
created
cgyarvin
username_1
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

>
comment
created
joshuareagan
username_0
"value" and "pattern" sound good.  What do you mean by "mode"?

"The regular, tall form of a `?:` Hoon expression start with the rune `?:` followed by a `gap`, and then three "value" ____s, each of which is separated from its neighbors by a `gap`."

We can fill in the blank with "subexpression" but maybe that's a mouthful.
comment
created
joshuareagan
username_0
Wait, I understand "mode" now.  Sorry about the delay.
comment
created
joshuareagan
username_0
Just to make sure I understand the proposal: "We have but one syntax, and two modes for parsing it.  The value mode happens when the compiler takes the source and makes an AST of tagged unions.  The pattern mode happens when the AST is parsed thereafter..."

I hate to play the same note over and over, but I'm not sure "one syntax, two modes" is the right way to go.  Because, strictly speaking, there really *isn't* one syntax.  The source file has `gap`s between subexpressions, and the AST product of the compiler doesn't.  This probably sounds pedantic, but it really isn't.  Of course there is an extremely tight semantic relationship between the two "modes", but mixing semantics and syntax in the documentation seems like a bad idea.  We're giving people a brand new network of concepts, which means they can't lean as heavily on experience and intuition to figure out what we're saying.  We have to make up for it by being really clear and precise in the docs.

Syntax is about the physically detectable symbols in front of the coder.  We should stick to that.
comment
created
joshuareagan
username_0
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.
comment
closed
joshuareagan
username_0
issue