bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: 9875@debbugs.gnu.org
> Date: Wed, 26 Oct 2011 18:21:01 -0400
> 
> >> I think the first step is to choose a single name for those, and then
> >> use it systematically.  I think we should simply call "window" the
> >> traditional "real" "live" "leaf" windows that display a buffer.  As for
> >> the other ones, we could go for "internal window", but I think "parent
> >> window" is better, tho maybe someone has a better idea ("compound
> >> window", "super window", ... ?)
> 
> > How about "window tree node" or just "node"?
> 
> Just "node" is much too vague for my taste.

I meant to use "node" only when "window tree node" was mentioned in
close proximity.  For example:

 -- User Option: window-nest
     If this variable is `nil', `split-window' creates a new node in
     the window tree if and only if the old window had no parent node
     or shall be split orthogonally to the combination it is part of.
     If this variable is non-`nil', `split-window' always creates a
     new node that becomes the parent node of the new window.  If this
     variable is always non-`nil', a frame's window tree is a binary
     tree so every node in the tree but the frame's window tree root
     has exactly one sibling node.

Compare this with what's currently in the manual:

 -- User Option: window-nest
     If this variable is `nil', `split-window' creates a new parent
     window if and only if the old window has no parent window or shall
     be split orthogonally to the combination it is part of.  If this
     variable is non-`nil', `split-window' always creates a new parent
     window.  If this variable is always non-`nil', a frame's window
     tree is a binary tree so every window but the frame's root window
     has exactly one sibling.

> "Window tree node" is a bit better but doesn't make it clear it's
> not a leaf and is a window object.

We will make that clear in the section where we describe the window
tree.  Once explained, it doesn't need to be mentioned again, if we
abstain as much as possible from mentioning the nodes of the tree in
other sections.

> For that reason I prefer "window parent".

That sounds mysterious, since it remains unclear what kind of thing is
this "parent".  "Parent node of the window" or "window's parent node"
is better.

> > That's what they are, right?
> 
> They aren't just "node" (i.e. some intermediate element pointing to
> others), they have most properties of windows, such as sizes and
> positions (tho they don't display any buffer).

That's true, but this fact is an implementation detail; we could
easily have the nodes be different Lisp objects.  E.g., some of the
attributes without which a live window is unthinkable are nil in these
"windows".  And it doesn't help that we don't say anywhere which
window attributes are non-trivially relevant to these "internal
windows".

So I think speaking about "nodes" instead will avoid confusion,
because otherwise whenever we talk about a "window", the reader will
always be in doubt whether this applies only to the "real", i.e. leaf
windows, or to the "internal" ones as well.