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.