the window tree, window-combination-limit

the window tree, window-combination-limit

[Mike Kupfer]

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

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?

Thanks for any illumination.

mike

"I understand just a little
No comprende--it's a riddle" --Wall of Voodoo, "Mexican Radio"

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

Re: the window tree, window-combination-limit

[Mike Kupfer]

martin rudalics wrote:

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

Hmm.  I ended up just running with

  (setq window-combination-resize t
        window-combination-limit nil)

for a few days to see if I like the behavior.  I do, but I don't
understand enough about what's happening to make any documentation
suggestions.  Thanks for taking the time to respond to my question.

warm regards,
mike

Re: the window tree, window-combination-limit

[John Yates]

[-- Attachment #1: Type: text/plain, Size: 467 bytes --]

On Thu, Dec 1, 2016 at 5:09 AM, martin rudalics <rudalics@gmx.at> wrote:

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


​I doubt that doc strings are the place to convey the window
management model.  A chapter in the reference manual would
be very much appreciated.

/john​

[-- Attachment #2: Type: text/html, Size: 1463 bytes --]

Re: the window tree, window-combination-limit

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Mon, 5 Dec 2016 11:43:30 -0500
> Cc: Emacs developers <emacs-devel@gnu.org>, Mike Kupfer <m.kupfer@acm.org>
> 
> On Thu, Dec 1, 2016 at 5:09 AM, martin rudalics <rudalics@gmx.at> wrote:
> 
>  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.
> 
> ​I doubt that doc strings are the place to convey the window
> management model. A chapter in the reference manual would
> be very much appreciated.

Martin wrote/extended such a chapter, see the node "Windows and
Frames", and the nodes which follow it, in the ELisp manual.  There's
also "Displaying Buffers" in the user manual, with its 2 sub-sections.

If you think something is missing or unclear there, please tell the
details, preferably as bug reports.

TIA