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

[Eli Zaretskii]

> Date: Thu, 27 Oct 2011 11:52:38 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: 9875@debbugs.gnu.org
> 
> The term "window" stands for an "arbitrary window" that is either an
> internal or a leaf window.  I want to be able to write text like
> 
>     A window is considered a "subwindow" of another window if it occupies
>     a part of that other window's screen area.

Why do you need to talk about subwindows at all?  AFAICS, this is used
(in about 5 more places, which is not a lot) in the context of
explaining the behavior when two or more windows are sibling leafs in
the tree.  If so, then using "sibling leaf nodes in the tree" will
explain it nicely.

>  >> Many important functions like `split-window', `delete-window', the
>  >> window resize functions, and obviously the new window tree functions
>  >> including `walk-window-tree' apply to both live and internal windows.
>  >
>  > That's true, but it only makes the whole issue more confusing.  I can
>  > easily and intuitively understand the expected effect of splitting a
>  > live window.  But what does it mean to "split" a window that is not
>  > displayed at all?  I don't know, and the manual doesn't explain.
> 
> The section on window splitting contains some five examples with
> drawings that explain what happens in this case.  What more can I do?

I appreciate your efforts.  But this bug is not about lack of effort.
This bug report is about methodological shortcomings of the result.
In a nutshell, by using terminology that is contrary to everyday
language and semantics, the current text makes it hard to understand,
because it goes against the intuitive meaning of "window" every reader
has wired into her mind.  No amount of explanations and examples will
ever be able to fight the natural tendency of our brains to think of
the white color when we read about "white", even if you define it as
something else and give a lot of examples.

>  > It
>  > only has this rather cryptic blurb:
>  >
>  >      If WINDOW is live, properties of the new window like margins and
>  >      scroll bars are inherited from WINDOW.  If WINDOW is an internal
>  >      window, these properties, as well as the buffer shown in the new
>  >      window, are inherited from the window selected on WINDOW's frame.
> 
> What precisely is cryptic here?

You need to read this in context.  Here's the beginning of the
description:

 -- Command: split-window &optional window size side
     This function creates a new window adjacent to WINDOW.  It returns
     the new window which is always a live window.

So now, when I read the above paragraph about live and internal
windows, I'm left with the following unsolved mysteries:

 . what does it mean "adjacent to WINDOW" when WINDOW is an internal
   one?

 . what happens to original WINDOW, as result of the split, if it was
   an internal one? does it occlude the new window or doesn't it, for
   example?

 . what other properties, besides margins and scroll bars are
   inherited from the selected window?

 . what buffer will be shown in the new window when WINDOW is a live
   one?

The text is cryptic because it leaves me with all those questions.
Significantly, if WINDOW is a live window, none of these questions
comes up, because it is clear what to expect.

>  > All the rest of the documentation of this function doesn't make any
>  > sense for an "internal window"; the description can only be understood
>  > in the context of a live window.  Take this part, for example:
>  >
>  >      If SIDE is `t' or `right' the new window will be positioned on the
>  >      right side of WINDOW.  The value `left' means the new window will
>  >      be located on the left side of WINDOW.  In both cases SIZE
>  >      specifies the new number of columns for WINDOW (or the new window
>  >      provided SIZE is negative) including space reserved for margins,
>  >      fringes and the scroll bar or a divider column.
>  >
>  > I cannot interpret this for a non-live window.  I could try _guessing_
>  > what this means in that case, but why should I need to guess when I'm
>  > reading the manual?
> 
> If you refer to this part "including space reserved for margins, fringes
> and the scroll bar or a divider column" then it's explaind in the text
> you considered cryptic above, namely that "these properties, as well as
> the buffer shown in the new window, are inherited from the window
> selected on WINDOW's frame".

No, I mean all of it: right, left, size, space reserved for margins,
fringes, scroll bars -- these attributes make no sense for a window
that isn't displayed.  They are just copies or sums of the attributes
of _real_ live windows that are children of this internal window.  It
is unnatural to talk about "size" or "side" of a window that doesn't
really exist on the screen!

>  > More importantly, does Joe R. Hacker, a casual Lisp programmer, really
>  > need to know what this does to an "internal" window?  And if he
>  > doesn't, maybe we will be much better off not to include those
>  > "internal" windows in the domain of these functions, simply by not
>  > calling them "windows"?
> 
> This means that Joe would not be able to split the root window of a
> frame, a thing I do quite frequently to get a live window at a side of
> the frame.

Which probably means we should have a function for that kind of thing,
so that J.R. Hacker could be oblivious to these intimate details.

>  > How can one _create_ a _new_ parent?  A parent can only be a parent if
>  > it has children.  You can create children of an existing parent, but
>  > you cannot create a _new_ parent for existing children.  This is a
>  > single most confusing sentence in this section.  It doesn't help that
>  > is also the most important sentence for understanding what window-nest
>  > does.
> 
> Splitting a window creates a new parent window due to the fact that
> splitting has to preserve the "identity" of the window that is split.
> Hence, the new parent window is spliced into the window tree in a
> single, atomic (on the Elisp level) action.  This means that I indeed
> "create a _new_ parent for" an already existing child or root window.

My point was that it is much easier and much more clear to say that a
new node is inserted into the window tree.  _That_ is something no
programmer needs explained.

>  >> Simply that functions accepting an internal window as argument would
>  >> have to say "the argument can be a window or a node" which doesn't
>  >> strike me as very constructive.  In particular not so because I then
>  >> would have to explain in the doc-string what a "node" is.
>  >
>  > I don't see any issue here.  Just say, somewhere close to the end of
>  > the doc string, something like "the argument WINDOW can also be a node
>  > of the frame's window tree".  It's very easy to understand.
> 
> I suppose you make the implicit assumption that the leaves of a tree are
> not considered nodes of the tree.

Okay, "the argument WINDOW can also be a non-leaf node of the frame's
window tree", if you must.

>  > I didn't suggest removing the information from the docs.  I only asked
>  > to (1) rename "internal windows" into "nodes of the window tree",
>  > which is what they are,
> 
> This would be misleading.  Live windows are also nodes of the window
> tree.

Our manuals are full of such "misleading" text.  We don't need to be
100% accurate in the mathematical sense of the word, just accurate
enough to get the idea across to the reader.

> Internal windows are elementary for understanding _how_ `split-window',
> `delete-window' and window resizing work.

Well, feel free to close this bug report, then.  This old fart now
knows how to read these sections, although it will always cost me a
non-trivial effort to mentally translate the text into what I consider
the right representation of the ideas.  I tried to explain why it
could be an obstacle for others.  I obviously fail to convince you.
Maybe we should have a second opinion.