Re: the window tree, window-combination-limit

[martin rudalics]

> The discussion for bug 25055 mentioned the variable
> window-combination-resize.  Since I frequently use balance-windows after
> splitting or deleting a window, window-combination-resize looked worth
> investigating.

With the ‘window-combination-resize’ approach, Emacs only operates on
the combination affected by a particular split or deletion.  Also, a
specific operation can override balancing without having to resort to
protecting window sizes.  ‘balance-windows’ and ‘balance-windows-area’
OTOH operate on all windows and will relentlessly resize all windows
that have not been protected.

> Its docstring (in 25.1.90) says
>
>    This variable takes no effect if the variable ‘window-combination-limit’ is
>    non-nil.
>
> so I also looked at window-combination-limit.  I have a couple questions
> as a result.
>
> The default value for window-combination-limit is 'window-size', which
> is documented as
>
>    ‘window-size’ means that splitting a window for displaying a buffer
>        makes a new parent window provided ‘display-buffer’ is supposed to
>        explicitly set the window’s size due to the presence of a
>        ‘window-height’ or ‘window-width’ entry in the alist used by
>        ‘display-buffer’.  Otherwise, this value is handled like nil.
>
> After several attempts I can parse the first sentence, but I'm having
> trouble understanding its significance.

Normally, when ‘window-combination-resize’ resize is non-nil, you have a
frame with two windows above each other and split one of these windows
via C-x 2, the emanating three windows all have approximately the same
height.  An invocation of ‘display-buffer’, however, might want to give
the new window a specific height.  For this purpose it has to override
the normal impact of ‘window-combination-resize’ but _only_ for this
particular split.  "Normal" C-x 2 splits are not affected by the default
setting of ‘window-combination-limit’.

I now tried to improve the doc-string of ‘window-combination-resize’ but
am aware that describing this option without describing the behavior in
much more detail and examples is fruitless.  Suggestions welcome.

> More generally, as a user, should I care about the window tree and
> parent windows?  A web search on
>
>    emacs parent window
>
> gives me several hits in the Emacs Lisp Reference Manual, but I don't
> see anything about the window tree in the Emacs Manual.  Can someone
> explain the different values for window-combination-limit in terms of
> what I would see as a user?

‘window-combination-limit’ is of minor interest for the user.  If it's
t, you can be sure that when you delete a window, it's space is always
given back to the window from where it was split off (or that window's
former ancestor if it has been deleted meanwhile).  This makes a
difference when that split was made by ‘split-window’ with the SIDE
argument ‘above’ or ‘left’.  Consider the following code:

(let* ((window-combination-limit nil)
       (window1 (split-window))
       (window2 (split-window window1 nil 'above)))
  (delete-window window2))

and compare it with

(let* ((window-combination-limit t)
       (window1 (split-window))
       (window2 (split-window window1 nil 'above)))
  (delete-window window2))

Also, if ‘window-combination-limit’ is nil, it's misused by a couple of
functions like ‘display-buffer’ to obtain a behavior that ascertains a
specific size for a new window or the creation of a parent window.

I'm afraid my explanations are not very illuminating.  It's easier to
answer specific questions ...

martin