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

[martin rudalics <rudalics@gmx.at>]

 >>  > 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  ...
 >
 > No, as _windows_.  Here's a typical example:
 >
 >      All other windows of a frame with the exception of the minibuffer
 >   window are subwindows of the frame's root window.  A window is
 >   considered a "subwindow" of another window if it occupies a part of
 >   that other window's screen area.
 >
 >      The functions described next allow to access the members of a window
 >   tree and take an arbitrary window as argument.
 >
 >    -- Function: window-parent &optional window
 >        Return WINDOW's parent in the window tree.  The optional argument
 >        WINDOW can denote an arbitrary window and defaults to the selected
 >        one.  The return value is `nil' if WINDOW is a minibuffer window
 >        or the root window of its frame and an internal window otherwise.
 >
 >      Parent windows do not appear on the screen.  The screen area of a
 >   parent window is the rectangular part of the window's frame occupied by
 >   the window's "child windows", that is, the set of windows having that
 >   window as their parent.  Each parent window has at least two child
 >   windows, so there are no "Matryoshka" windows.  Minibuffer windows do
 >   not have child windows.
 >
 > All this text freely talks about "windows" when it really means the
 > nodes of the window tree.

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.

instead of

    A node of the window tree or a live window are considered a
    "subwindow" or "a subnode of the window tree" of a node of the window
    tree if they occupy a part of that node's screen area.

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

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

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

Note that the present inheritance mechanism is annoying in the first
place because it makes us calculate the size of the new window based on
properties of the window to split.  In at least one case this has made
me rewrite these calculations when a user wanted to split off a two
lines high window from a window with a headerline.

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

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

 >> 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.  I do not understand that assumption.
Where did you get it from?

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

 > and (2) have a single section in the manual
 > that describes the window tree and the functions that operate on it,
 > instead of spreading that over several sections.  The information you
 > want that person to have will still be available.  But it will be out
 > of the way of all the other 99% of Lisp programmers who have no need
 > to know all that, and don't need to be confused by these "internal"
 > windows.

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

martin