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

[martin rudalics <rudalics@gmx.at>]

 > This node starts fine, by describing window-frame and window-list.
 > Then it begins to describe the "window tree", and that's where things
 > go wrong.  The main problem is that the non-leaf nodes of the window
 > tree are referred to as "windows",

... as "internal windows" more precisely  ...

 > which makes it all too easy to
 > confuse them with the leafs of the window tree, each one of which
 > corresponds to a real live window displayed on the frame.  This is
 > fundamentally wrong, because there's a significant difference between
 > the "normal" (a.k.a. "live") windows and the nodes of the window
 > tree.

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.

 > The confusion thereafter continues in the next sections of the
 > "Windows" chapter, as these "windows" are sometimes called "internal
 > windows", sometimes contrasted with "live" windows.

Hopefully wherever such a contrast is required.

 > The confusion
 > culminates in "Splitting Windows", where many issues are described via
 > window-parent and what is called "creating a new parent".

Yes. And I probably gave too many examples for this in the expectation
that readers would study them and get a feeling for what internal
windows are needed for.  But what is the culminating confusion here?
Could you provide at least one example?

 > I submit these confusing references to the nodes of the window tree as
 > "windows" should be removed.  If we want to talk about the window
 > tree, let's talk about a tree with nodes; let's not call them
 > "windows".  I know that each node is exposed to Lisp as a window
 > object, but (a) I'm not sure this is a good idea either, and (b) what
 > harm will be done if we mention this factoid in some place and
 > immediately forget about it?

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 guess what I'm saying is this: let's have a single section named
 > "The Window Tree" which describes the tree and what can be done with
 > its nodes from a Lisp program, and let's describe all the other
 > window-related operations without any reference to the tree or its
 > nodes.  I submit that most Lisp programmers will never need to go to
 > the level of the tree, unless they want to understand the internal
 > operation of windows.el or rewrite it from scratch.

Given the fact that a function like `frame-root-window' (which would
return a "node" in your parlance whenever we have two live windows) is
in Emacs since 1992 at least and a documentation of that function has
been reqeusted recently here on this forum, I suppose that at least some
Lisp programmers need to go to the level of the tree.

Let's take an example: I wrote two functions called `window-state-get'
and `window-state-put' in the hope that eventually someone uses these
functions in order to write window configurations to a file and reuse
them in a later session.  If we find someone to do that, that person
must be interested in internal windows, because these are part of the
state and prescribe how to obtain the original configuration from that
state.  Debugging or patching these functions without knowing about
internal windows is virtually impossible.

martin