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

[Daniel Martín]

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.