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

From: martin rudalics <[email-masked]>
Date: Thu, 27 Oct 2011 15:16:13 +0200

>> 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?

Because I didn't give this a thought yet ;-)

 > 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.

A subwindow can be an internal window.

 > 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.

Then this problem existed through the term `frame-root-window' for more
than twenty years without anyone ever complaining.  Ever tried

(windowp (frame-root-window))

in Emacs < 24?  And when the function `window-tree' was added a couple
of Emacsen ago, no one complained about its documentation either.

 > 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.

An object can be white even if it's hidden beneath another one.

 > 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?

The same as for a live window.  Internal windows have edges just as live
windows do.

 >  . 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?

It's shrunk just as a live window.

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

All those it would inherit from WINDOW if WINDOW were live.

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

WINDOW's buffer.

 > 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.

Not for me.  I don't know, for example, if the new window will get a
header line or not.

 >> 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!

Nevertheless internal windows have sizes and sides and I continuously
work with them.  To know whether an arbitrary window is full-width I
compare its width to that of the frame's root window (and not to the
width 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.

We had plenty of that in the buffer display code people didn't like.

 >> 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.

But normally a tree is expanded by converting a leaf node into an
internal node.  Just that Emacs has different requirements ...

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

So Joe has to to be familiar with "nodes" and the "window tree" when
reading the doc-string of `delete-window'?

 >> 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.

But when we write new text we should try to be as accurate as possible.
Don't you agree?

martin