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

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

[Eli Zaretskii]

emacs -Q
C-h i
m elisp RET
g Windows and Frames RET

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

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

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?

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.


In GNU Emacs 24.0.90.87 (x86_64-unknown-linux-gnu, GTK+ Version 2.20.1)
 of 2011-10-26 on fencepost.gnu.org
configured using `configure  '--enable-asserts' '--enable-checking' '--with-gif=no' '--with-tiff=no' 'CFLAGS=-ggdb -g3 -O0 -DGLYPH_DEBUG=1''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: nil
  value of $XMODIFIERS: nil
  locale-coding-system: nil
  default enable-multibyte-characters: t

Major mode: RMAIL

Minor modes in effect:
  shell-dirtrack-mode: t
  display-time-mode: t
  show-paren-mode: t
  savehist-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t

Recent input:
ESC O A ESC O A ESC O A ESC O A ESC O A ESC O D ESC 
O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D 
ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC 
O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D 
ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC 
O D ESC O D ESC O B ESC O B ESC O B ESC O B ESC O B 
ESC O B ESC O B C-e SPC a b o u t ESC q ESC O B ESC 
O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B 
ESC O B ESC O B ESC < C-c C-c d C-u 1 0 2 2 j C-x C-s 
ESC ! ESC O A RET ESC x ESC O A RET ESC O A ESC O A 
ESC O A RET C-s 0 6 : 2 0 : 1 4 C-s C-s ESC O B ESC 
[ 6 ~ ESC O A ESC O B C-x C-x C-w C-x C-s C-x k RET 
C-u g ESC O A RET SPC C-z C-z C-z C-z d SPC SPC d d 
d d SPC d d d d d d d d d C-x C-s C-x b RET ESC < u 
ESC O A ESC O A ESC O A ESC O A RET SPC SPC SPC SPC 
SPC SPC C-x b RET ESC x r e p o r t - e m TAB RET

Recent messages:
Computing summary lines...done
14 new messages read
Showing message 1025
Showing message 1025...done
Showing message 1036
Showing message 1036...done
No following nondeleted message
Saving file /home/e/eliz/INBOX...
Wrote /home/e/eliz/INBOX [2 times]
Mark set

Load-path shadows:
None found.

Features:
(shadow emacsbug iso-transl info multi-isearch pp help-mode view
help-fns dabbrev newcomment flyspell ispell shell pcomplete comint
ring rmailsum qp rmailmm message sendmail regexp-opt format-spec
rfc822 mml easymenu mml-sec mm-decode mm-bodies mm-encode mailabbrev
gmm-utils mailheader mail-parse rfc2231 rmail rfc2047 rfc2045
ietf-drums mm-util mail-prsvr mail-utils time paren cus-start cus-load
time-date savehist saveplace tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image fringe
lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer loaddefs button faces cus-face files text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process
dynamic-setting font-render-setting move-toolbar gtk x-toolkit x
multi-tty emacs)

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

[Stefan Monnier]

> 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", which makes it all too easy to
> confuse them with the leafs of the window tree, each one of which

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", ... ?)


        Stefan

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

[martin rudalics]

 > 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

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: 9875@debbugs.gnu.org
> Date: Wed, 26 Oct 2011 10:17:18 -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"?  That's what they are,
right?

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

[Eli Zaretskii]

> Date: Wed, 26 Oct 2011 16:23:05 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: 9875@debbugs.gnu.org
> 
>  > 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  ...

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.

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

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?

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

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

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.

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

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

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

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

[Stefan Monnier]

>> 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.  "Window tree node" is a bit
better but doesn't make it clear it's not a leaf and is a window object.
For that reason I prefer "window parent".

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


        Stefan

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

[Eli Zaretskii]

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

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

[martin rudalics]

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

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

[martin rudalics]

 > That's true, but this fact is an implementation detail; we could
 > easily have the nodes be different Lisp objects.

Certainly not.  If you look into the window resizing code you will see
that it treats internal and leaf windows alike.  Changing the underlying
representation would have meant to double the work done there.

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

This is usually said in the second sentence of the doc-string.  For
`split-window' it reads

   "WINDOW can be any window and defaults to the selected one."

And for `set-window-buffer' we have

   "WINDOW has to be a live window and defaults to the selected one."

Let's not spoil this very simple recipe.

martin

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.

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

[Eli Zaretskii]

> Date: Thu, 27 Oct 2011 11:56:16 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: Stefan Monnier <monnier@iro.umontreal.ca>, 9875@debbugs.gnu.org
> 
>  > That's true, but this fact is an implementation detail; we could
>  > easily have the nodes be different Lisp objects.
> 
> Certainly not.  If you look into the window resizing code you will see
> that it treats internal and leaf windows alike.  Changing the underlying
> representation would have meant to double the work done there.

It's clear that representing the non-leaf nodes as window objects was
chosen because it's convenient from the implementation POV.  But that
doesn't mean we need to expose this to every place where we describe
how windows are split and resized.

>  > 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.
> 
> This is usually said in the second sentence of the doc-string.  For
> `split-window' it reads
> 
>    "WINDOW can be any window and defaults to the selected one."

When J.R. Hacker reads about "any window", she will definitely have
only live windows in mind.

> And for `set-window-buffer' we have
> 
>    "WINDOW has to be a live window and defaults to the selected one."

Which immediately begs the question "how can a window not be `live'"?

> Let's not spoil this very simple recipe.

Simple is in the eye of the beholder.

And I was talking about the manual, not the doc strings, btw.

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

[Stefan Monnier]

> That sounds mysterious, since it remains unclear what kind of thing is
> this "parent".

Sorry, I meant "parent window".


        Stefan

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

[Stefan Monnier]

> Which immediately begs the question "how can a window not be `live'"?

C-h f window-live-p RET
This has existed for a long time,


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: martin rudalics <rudalics@gmx.at>,  9875@debbugs.gnu.org
> Date: Thu, 27 Oct 2011 08:36:40 -0400
> 
> > Which immediately begs the question "how can a window not be `live'"?
> 
> C-h f window-live-p RET

I know that, sigh...

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

[martin rudalics]

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

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

[martin rudalics]

 > It's clear that representing the non-leaf nodes as window objects was
 > chosen because it's convenient from the implementation POV.  But that
 > doesn't mean we need to expose this to every place where we describe
 > how windows are split and resized.

True.  But the Elisp manual is about reading and writing Elisp code.
And the necessary distinction in descriptions is in just one word -
"any" or "live".

 >> This is usually said in the second sentence of the doc-string.  For
 >> `split-window' it reads
 >>
 >>    "WINDOW can be any window and defaults to the selected one."
 >
 > When J.R. Hacker reads about "any window", she will definitely have
 > only live windows in mind.

And what would be so bad about that?  A lost opportunity.  When Joe
grows up he will read the text more carefully and maybe even appreciate
what he finds there.

 >> And for `set-window-buffer' we have
 >>
 >>    "WINDOW has to be a live window and defaults to the selected one."
 >
 > Which immediately begs the question "how can a window not be `live'"?

And how could you live with a text like

    For practical purposes, a window exists only while it is displayed in
a frame.  Once removed from the frame, the window is effectively deleted
and should not be used, _even though there may still be references to
it_ from other Lisp objects; see *Note Deleting Windows::.  Restoring a
saved window configuration is the only way for a window no longer on the
screen to come back to life; see *Note Window Configurations::.

all those years?

 > Simple is in the eye of the beholder.
 >
 > And I was talking about the manual, not the doc strings, btw.

Which have to be consistent, btw.

martin

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

[Juri Linkov]

> It is unnatural to talk about "size" or "side" of a window that
> doesn't really exist on the screen!

FWIW, I have no problem imagining a window that doesn't really exist
on the screen.  I imagine it as an "abstract window" with invisible
outlines that group visible windows.  So I have no problem understanding
"internal windows" when reading the documentation.

It seems the source of your complaints is the duality of window
representation: data and view.  When manipulating the window tree
(e.g. when saving/restoring the window tree) it makes sense to think
in terms of data - window tree with nodes.  But when manipulating
windows of the screen (e.g. when splitting windows), it makes sense
to think in terms of visual representation where "internal windows"
are distinct objects (albeit invisible).

So thinking about "internal windows" requires imagination skills.
But diagrams in the Info manual help greatly.

The only problem with these diagrams is that ASCII art
doesn't distinguish between internal and live windows:

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      ||| ___________  ___________ |||
         ||      ||||           ||           ||||
         ||      ||||           ||           ||||
         ||      ||||_____W6____||_____W7____||||
         ||      |||____________W4____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

It would help to draw live and internal windows with different lines, e.g.

          ______________________________________
         |******** ____________________________ |
         |*      *| __________________________ ||
         |*      *||**************************|||
         |*      *||*           **           *|||
         |*      *||*           **           *|||
         |*      *||******W6***********W7*****|||
         |*      *||____________W4____________|||
         |*      *|****************************||
         |*      *|*                          *||
         |*      *|*************W5*************||
         |***W2***|_____________W3_____________ |
         |__________________W1__________________|

but this is ugly and I can't find a better way to draw them.

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

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: martin rudalics <rudalics@gmx.at>,  9875@debbugs.gnu.org
> Date: Fri, 28 Oct 2011 11:04:35 +0300
> 
> > It is unnatural to talk about "size" or "side" of a window that
> > doesn't really exist on the screen!
> 
> FWIW, I have no problem imagining a window that doesn't really exist
> on the screen.

I also "have no problem" imagining that, but it requires my brain
muscles to make a conscious effort each time I meet the word
"window".  Such efforts should not be required when reading about such
a basic concept.

> The only problem with these diagrams is that ASCII art
> doesn't distinguish between internal and live windows:

Both Texinfo and Emacs's Info reader support images for quite some
time.

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

[Drew Adams]

> The only problem with these diagrams is that ASCII art
> doesn't distinguish between internal and live windows:
>           ______________________________________
>          | ______  ____________________________ |
>          ||      || __________________________ ||
>          ||      ||| ___________  ___________ |||
>          ||      ||||           ||           ||||
>          ||      ||||           ||           ||||
>          ||      ||||_____W6____||_____W7____||||
>          ||      |||____________W4____________|||
>          ||      || __________________________ ||
>          ||      |||                          |||
>          ||      |||____________W5____________|||
>          ||__W2__||_____________W3_____________ |
>          |__________________W1__________________|
> 
> It would help to draw live and internal windows with 
> different lines, e.g.
> 
>           ______________________________________
>          |******** ____________________________ |
>          |*      *| __________________________ ||
>          |*      *||**************************|||
>          |*      *||*           **           *|||
>          |*      *||*           **           *|||
>          |*      *||******W6***********W7*****|||
>          |*      *||____________W4____________|||
>          |*      *|****************************||
>          |*      *|*                          *||
>          |*      *|*************W5*************||
>          |***W2***|_____________W3_____________ |
>          |__________________W1__________________|
> 
> but this is ugly and I can't find a better way to draw them.

Just use a different label/name convention: IW3 (or I3 or N3 or ...) for
internal windows.  (Mention the convention in the text, of course.)