bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

In the Elisp manual, under "37.3 Retrieving Nodes" there is this text:

   We talk about a node being “smaller” or “larger”, and “lower” or
“higher”.  A smaller and lower node is lower in the syntax tree and
therefore spans a smaller portion of buffer text; a larger and higher
node is higher up in the syntax tree, it contains many smaller nodes as
its children, and therefore spans a larger portion of text.

I think the concepts of nodes being "lower" and "higher" are more or
less clear, and the notation is similar to the one used in classic texts
about rooted trees.  However, the concepts of "smaller" and "larger" are
not very clear to me.  From the text, it seems that "lower" also means
"smaller", and "higher" always means "larger".  Is that correct, or
"smaller" and "larger" are really orthogonal to "lower" and "higher"?
If that's the case, I think the text needs some clarification, ideally
with a brief example.

Thanks.

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Eli Zaretskii]

> Date: Wed, 04 Jan 2023 15:29:14 +0100
> From:  Daniel Martín via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> 
> In the Elisp manual, under "37.3 Retrieving Nodes" there is this text:
> 
>    We talk about a node being “smaller” or “larger”, and “lower” or
> “higher”.  A smaller and lower node is lower in the syntax tree and
> therefore spans a smaller portion of buffer text; a larger and higher
> node is higher up in the syntax tree, it contains many smaller nodes as
> its children, and therefore spans a larger portion of text.
> 
> I think the concepts of nodes being "lower" and "higher" are more or
> less clear, and the notation is similar to the one used in classic texts
> about rooted trees.  However, the concepts of "smaller" and "larger" are
> not very clear to me.  From the text, it seems that "lower" also means
> "smaller", and "higher" always means "larger".  Is that correct, or
> "smaller" and "larger" are really orthogonal to "lower" and "higher"?

They aren't orthogonal, AFAIU.  The text actually says that "lower"
necessarily also means "smaller".

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Wed, 04 Jan 2023 15:29:14 +0100
>> From:  Daniel Martín via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> 
>> In the Elisp manual, under "37.3 Retrieving Nodes" there is this text:
>> 
>>    We talk about a node being “smaller” or “larger”, and “lower” or
>> “higher”.  A smaller and lower node is lower in the syntax tree and
>> therefore spans a smaller portion of buffer text; a larger and higher
>> node is higher up in the syntax tree, it contains many smaller nodes as
>> its children, and therefore spans a larger portion of text.
>> 
>> I think the concepts of nodes being "lower" and "higher" are more or
>> less clear, and the notation is similar to the one used in classic texts
>> about rooted trees.  However, the concepts of "smaller" and "larger" are
>> not very clear to me.  From the text, it seems that "lower" also means
>> "smaller", and "higher" always means "larger".  Is that correct, or
>> "smaller" and "larger" are really orthogonal to "lower" and "higher"?
>
> They aren't orthogonal, AFAIU.  The text actually says that "lower"
> necessarily also means "smaller".

If that's the case, I don't feel the text is clear enough about the
"necessarily" part. I think the text would be more clear if the first
sentence was

  We talk about a node being “smaller” (or "lower") and “larger” (or
  “higher”).

The next sentence should avoid "smaller and lower" and "larger and
higher", because it'd be redundant (can a node be "smaller and
higher"?). That is, I suggest the following text instead:

  A smaller node is lower in the syntax tree and therefore spans a
smaller portion of buffer text; a larger node is higher up in the syntax
tree, it contains many smaller nodes as its children, and therefore
spans a larger portion of text.

Thanks.

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Eli Zaretskii]

> From: Daniel Martín <mardani29@yahoo.es>
> Cc: 60555@debbugs.gnu.org
> Date: Thu, 05 Jan 2023 00:05:43 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > They aren't orthogonal, AFAIU.  The text actually says that "lower"
> > necessarily also means "smaller".
> 
> If that's the case, I don't feel the text is clear enough about the
> "necessarily" part. I think the text would be more clear if the first
> sentence was
> 
>   We talk about a node being “smaller” (or "lower") and “larger” (or
>   “higher”).

Adding parentheses makes the text harder to read, IME.  You kept all
the words and the sentence structure, so everything else is unchanged,
and the added complexity isn't justified, IMO.

> The next sentence should avoid "smaller and lower" and "larger and
> higher", because it'd be redundant (can a node be "smaller and
> higher"?).  That is, I suggest the following text instead:
> 
>   A smaller node is lower in the syntax tree and therefore spans a
> smaller portion of buffer text; a larger node is higher up in the syntax
> tree, it contains many smaller nodes as its children, and therefore
> spans a larger portion of text.

I think these micro-changes are basically splitting hair, and the text
you propose will almost certainly be less clear for someone.  If the
original text is unclear, the way to fix that is to rewrite it in a
completely different way.  If you try explaining what exactly confuses
you, maybe I could come up with such a rewrite.  I cannot myself
understand what's unclear, because to me it sounds very clear and
simple to understand.  So I need your help.  Try to recollect what
confused you when you first read this.

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>
> I think these micro-changes are basically splitting hair, and the text
> you propose will almost certainly be less clear for someone.  If the
> original text is unclear, the way to fix that is to rewrite it in a
> completely different way.  If you try explaining what exactly confuses
> you, maybe I could come up with such a rewrite.  I cannot myself
> understand what's unclear, because to me it sounds very clear and
> simple to understand.  So I need your help.  Try to recollect what
> confused you when you first read this.

My main confusion happened after reading this sentence:

  We talk about a node being “smaller” or “larger”, and “lower” or
“higher”.

That made me think there are two different dimensions we classify nodes:
"Size", that is, if the node is small or large, and "height", that is,
if it is low or high.  I was hoping to learn the differences between
"size" and "height" in the rest of the text, but the text didn't make it
clear to me because it only talks about "smaller and lower" and "larger
and higher".  What about "smaller and higher", or "larger and lower"?
Are they possible at all?  After reading everything, I got the idea that
the terms may actually be synonyms, but I was not 100% sure.  I feel we
could make this more clear from the start.

All of this is my perspective as a non-native English speaker.  Hope
this helps.

Thanks.

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Eli Zaretskii]

> From: Daniel Martín <mardani29@yahoo.es>
> Cc: 60555@debbugs.gnu.org
> Date: Thu, 05 Jan 2023 10:44:55 +0100
> 
> >
> > I think these micro-changes are basically splitting hair, and the text
> > you propose will almost certainly be less clear for someone.  If the
> > original text is unclear, the way to fix that is to rewrite it in a
> > completely different way.  If you try explaining what exactly confuses
> > you, maybe I could come up with such a rewrite.  I cannot myself
> > understand what's unclear, because to me it sounds very clear and
> > simple to understand.  So I need your help.  Try to recollect what
> > confused you when you first read this.
> 
> My main confusion happened after reading this sentence:
> 
>   We talk about a node being “smaller” or “larger”, and “lower” or
> “higher”.
> 
> That made me think there are two different dimensions we classify nodes:
> "Size", that is, if the node is small or large, and "height", that is,
> if it is low or high.  I was hoping to learn the differences between
> "size" and "height" in the rest of the text, but the text didn't make it
> clear to me because it only talks about "smaller and lower" and "larger
> and higher".  What about "smaller and higher", or "larger and lower"?
> Are they possible at all?  After reading everything, I got the idea that
> the terms may actually be synonyms, but I was not 100% sure.  I feel we
> could make this more clear from the start.
> 
> All of this is my perspective as a non-native English speaker.  Hope
> this helps.

Thanks, I've now reworded that text, please take a look.

bug#60555: 29.0.50; Some clarification is needed about "smaller" and "larger" Tree-sitter nodes

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> 
>> My main confusion happened after reading this sentence:
>> 
>>   We talk about a node being “smaller” or “larger”, and “lower” or
>> “higher”.
>> 
>> That made me think there are two different dimensions we classify nodes:
>> "Size", that is, if the node is small or large, and "height", that is,
>> if it is low or high.  I was hoping to learn the differences between
>> "size" and "height" in the rest of the text, but the text didn't make it
>> clear to me because it only talks about "smaller and lower" and "larger
>> and higher".  What about "smaller and higher", or "larger and lower"?
>> Are they possible at all?  After reading everything, I got the idea that
>> the terms may actually be synonyms, but I was not 100% sure.  I feel we
>> could make this more clear from the start.
>> 
>> All of this is my perspective as a non-native English speaker.  Hope
>> this helps.
>
> Thanks, I've now reworded that text, please take a look.

Thanks, the text is now clearer to me.  I'm closing the bug.