bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Drew Adams]

We should document more explicitly how to obtain the window-splitting
behavior for buffer display that existed prior to Emacs 23.  The NEWS
says only this:
 
 "*** display-buffer tries to be smarter when splitting windows.  The
 new option split-window-preferred-function lets you specify your own
 function to pop up new windows.  Its default value
 split-window-sensibly can split a window either vertically or
 horizontally, whichever seems more suitable in the current
 configuration.  You can tune the behavior of split-window-sensibly by
 customizing split-height-threshold and the new option
 split-width-threshold.  Both options now take the value nil to
 inhibit splitting in one direction.  Setting split-width-threshold to
 nil inhibits horizontal splitting and gets you the behavior of Emacs
 22 in this respect.  In any case, display-buffer may now split the
 largest window vertically even when it is not as wide as the
 containing frame."
 
Most of that just describes the new behavior, repeating what is in the
manual.  That's OK, but insufficient for NEWS.
 
The last two sentences are all that is said about how to get the
pre-Emacs 23 behavior, and they speak only about horizontal splitting.
 
Nothing is said about how to get the pre-Emacs 23 behavior for
_choosing which window is split_, and that change is a radical
departure from previous behavior - a change just as important as the
change regarding horizontal splitting.
 
It seems (but I'm not sure this works for all cases) that what is
needed, to ensure that the same window as before is split, is to bind
`split-window-preferred-function' to something like this around calls
to `display-buffer':
 
(lambda (w) (eq w (get-lru-window)))
 
Even if this function is not an exact recipe for all cases, something
like it should be mentioned, to help users get back the behavior that
existed before the new "smarter" behavior was introduced.  Preferably,
Emacs would itself provide a function that users could use here - a
function that would give precisely the pre-23 behavior in all cases.
 
We should also make it clear that if you want the pre-23 behavior then
you will need to wrap not only explicit calls to `display-buffer' with
a `let' binding this way, but also calls to things such as
`with-output-to-temp-buffer'.
 
 
 
In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[martin rudalics]

 > It seems (but I'm not sure this works for all cases) that what is
 > needed, to ensure that the same window as before is split, is to bind
 > `split-window-preferred-function' to something like this around calls
 > to `display-buffer':
 >
 > (lambda (w) (eq w (get-lru-window)))

The function you want might be

(defun split-window-22 (window)
   (let ((frame (window-frame window)))
     (or (and (setq window (get-largest-window frame t))
	     (window-full-width-p window)
	     (window-splittable-p window)
	     (split-window window))
	(and (setq window (get-lru-window frame t))
	     (window-splittable-p window)
	     (split-window window)))))

but I wouldn't rely on it.

 > Even if this function is not an exact recipe for all cases, something
 > like it should be mentioned, to help users get back the behavior that
 > existed before the new "smarter" behavior was introduced.  Preferably,
 > Emacs would itself provide a function that users could use here - a
 > function that would give precisely the pre-23 behavior in all cases.
 >
 > We should also make it clear that if you want the pre-23 behavior then
 > you will need to wrap not only explicit calls to `display-buffer' with
 > a `let' binding this way, but also calls to things such as
 > `with-output-to-temp-buffer'.

All people have to do is customize `split-window-preferred-function' to
that function.

martin

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Drew Adams]

>  > It seems (but I'm not sure this works for all cases) that what is
>  > needed, to ensure that the same window as before is split, 
>  > is to bind `split-window-preferred-function' to something like
>  > this around calls to `display-buffer':
>  > (lambda (w) (eq w (get-lru-window)))
> 
> The function you want might be
> 
> (defun split-window-22 (window)
>    (let ((frame (window-frame window)))
>      (or (and (setq window (get-largest-window frame t))
> 	     (window-full-width-p window)
> 	     (window-splittable-p window)
> 	     (split-window window))
> 	(and (setq window (get-lru-window frame t))
> 	     (window-splittable-p window)
> 	     (split-window window)))))
> 
> but I wouldn't rely on it.

Thanks for this info, Martin. For the particular code I had in mind the simpler
version I wrote above works, but I understand the difference.

>  > Even if this function is not an exact recipe for all 
>  > cases, something like it should be mentioned, to help users
>  > get back the behavior that existed before the new "smarter"
>  > behavior was introduced. Preferably, Emacs would itself provide
>  > a function that users could use here - a function that would
>  > give precisely the pre-23 behavior in all cases.
>  >
>  > We should also make it clear that if you want the pre-23 
>  > behavior then you will need to wrap not only explicit calls to 
>  > `display-buffer' with a `let' binding this way, but also calls
>  > to things such as `with-output-to-temp-buffer'.
> 
> All people have to do is customize
> `split-window-preferred-function' to that function.

No, I'm talking about code, not a broad user preference setting. Code that
wants, for example, to work with various releases.

But yes, that's my point: We should tell users that they can bind
`split-window-preferred-function' to such a function to get Emacs 22/21/20
behavior wrt window splitting. I suggest we provide such a function, and mention
it in the doc string. If the function you wrote above isn't perfect, it's still
probably pretty good. Bug reports will help perfect it, if need be.

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[martin rudalics]

 > No, I'm talking about code, not a broad user preference setting. Code that
 > wants, for example, to work with various releases.

Such code should get fixed in order to not rely on the heuristics of any
release.  With Emacs 23 you can bind `window-size-fixed' around calls to
`display-buffer' in order to avoid that a particular window gets split.
With Emacs 22 `display-buffer' usually throws an error when the largest
or LRU window has fixed size.

martin

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Stefan Monnier]

> No, I'm talking about code, not a broad user preference setting. Code that
> wants, for example, to work with various releases.

We're talking about `display-buffer', which is a function that provides
no guarantee about where the window gets displayed, so code that uses it
should be prepared for surprises.  If you argue that code should have
more control over it, I agree.

I suggested changing the `not-this-window' argument so it can have
a description of the recommended window to use (not a specific window,
but something that could specify whether it should be on the same-frame
or not, in an adjacent window or not, in a preferably tall/wide window,
in a window close to the minibuffer, ...).


        Stefan

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[martin rudalics]

 > We're talking about `display-buffer', which is a function that provides
 > no guarantee about where the window gets displayed, so code that uses it
 > should be prepared for surprises.  If you argue that code should have
 > more control over it, I agree.

IMHO `display-buffer' has to follow (a) changes in display technology
and (b) user preferences.  (a) implies that code cannot rely upon which
window gets split or how that window is split accross future versions of
Emacs.  (b) implies that code using `display-buffer' must be aware of
user preferences.

If coders want precise control, they should use `set-window-buffer'.

 > I suggested changing the `not-this-window' argument so it can have
 > a description of the recommended window to use (not a specific window,
 > but something that could specify whether it should be on the same-frame
 > or not, in an adjacent window or not, in a preferably tall/wide window,
 > in a window close to the minibuffer, ...).

The `not-this-window' argument should be used with caution because it
already now overrides user preferences wrt to `display-buffer'.  I think
that only if the user does not specify any preference in `pop-up-frames'
or `pop-up-windows', an application should be allowed to override that.
So we should enhance the semantics of these variables first.

In addition, I think `window-size-fixed' should be handled the way we
treat dedicated windows.  That is, when this is non-nil for a particular
window, it should inhibit that `display-buffer' splits that window.  But
only the value `t' should inhibit that the window can be resized
manually.  Thus an application can set `window-size-fixed' to some
non-nil, non-t value to avoid that the window gets split and/or resized
by `display-buffer'.

Also `display-buffer' should call `split-window-preferred-function' at
most once.  Calling it with the largest and the LRU window (which may
designate one and the same window) appears merely disconcerting.

martin

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Drew Adams]

> IMHO `display-buffer' has to follow (a) changes in display technology
> and (b) user preferences.  (a) implies that code cannot rely 
> upon which window gets split or how that window is split accross future 
> versions of Emacs.  (b) implies that code using `display-buffer' must
> be aware of user preferences.
> 
> If coders want precise control, they should use `set-window-buffer'.
> 
> The `not-this-window' argument should be used with caution because it
> already now overrides user preferences wrt to `display-buffer'.
> I think that only if the user does not specify any preference in 
> `pop-up-frames' or `pop-up-windows', an application should be allowed
> to override that. So we should enhance the semantics of these
> variables first.
> 
> In addition, I think `window-size-fixed' should be handled the way we
> treat dedicated windows.  That is, when this is non-nil for a 
> particular window, it should inhibit that `display-buffer' splits
> that window.  But only the value `t' should inhibit that the window
> can be resized manually.  Thus an application can set
> `window-size-fixed' to some non-nil, non-t value to avoid that the
> window gets split and/or resized by `display-buffer'.
> 
> Also `display-buffer' should call `split-window-preferred-function' at
> most once.  Calling it with the largest and the LRU window (which may
> designate one and the same window) appears merely disconcerting.

The more you guys play with this, changing behavior, the more users and
programmers have to jump through hoops to keep up with the changes. Let it be.
At least for a few years. ;-)

Something like `display-buffer' is fundamental, core, ubiquitous. When you mess
with it (in attempts to improve it), you mess with Emacs and Emacs users in
fundamental ways.

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Stefan Monnier]

> Also `display-buffer' should call `split-window-preferred-function' at
> most once.  Calling it with the largest and the LRU window (which may
> designate one and the same window) appears merely disconcerting.

Agreed.  I have no idea why it's called several times as of now.
It clearly isn't due to backward compatibility since this is new in
Emacs 23.


        Stefan

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[martin rudalics]

 >> Also `display-buffer' should call `split-window-preferred-function' at
 >> most once.  Calling it with the largest and the LRU window (which may
 >> designate one and the same window) appears merely disconcerting.
 >
 > Agreed.  I have no idea why it's called several times as of now.
 > It clearly isn't due to backward compatibility since this is new in
 > Emacs 23.

It is due to backward compatibility.  The only new thing here is that
`split-window-preferred-function' can decide whether and how to split
the window.  If it returns nil for the first call it will be called a
second time, though.

martin

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Stefan Monnier]

>>> Also `display-buffer' should call `split-window-preferred-function' at
>>> most once.  Calling it with the largest and the LRU window (which may
>>> designate one and the same window) appears merely disconcerting.
>> 
>> Agreed.  I have no idea why it's called several times as of now.
>> It clearly isn't due to backward compatibility since this is new in
>> Emacs 23.

> It is due to backward compatibility.  The only new thing here is that
> `split-window-preferred-function' can decide whether and how to split
> the window.  If it returns nil for the first call it will be called a
> second time, though.

Huh?  Emacs-22 does not have `split-window-preferred-function', so
I can't see how backward compatibility comes into the picture.


        Stefan

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Drew Adams]

> Huh?  Emacs-22 does not have `split-window-preferred-function', so
> I can't see how backward compatibility comes into the picture.

Please don't mess with this anymore. Just let it be.

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[martin rudalics]

 > Huh?  Emacs-22 does not have `split-window-preferred-function', so
 > I can't see how backward compatibility comes into the picture.

`split-window-preferred-function' is a stand-in for `split-window' and
that was called up to two times by Emacs 22.  Or did you intend to move
the `get-largest-window' and `get-lru-window' calls and the check
whether the resulting frame is splittable to `split-window-sensibly'?

martin

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Stefan Monnier]

>> Huh?  Emacs-22 does not have `split-window-preferred-function', so
>> I can't see how backward compatibility comes into the picture.
> `split-window-preferred-function' is a stand-in for `split-window' and
> that was called up to two times by Emacs 22.  Or did you intend to move
> the `get-largest-window' and `get-lru-window' calls and the check
> whether the resulting frame is splittable to `split-window-sensibly'?

So you're saying that it's difficult to preserve the old behavior,
introduce split-window-preferred-function and also make sure that
split-window-preferred-function is only called once?

I guess you're right.  It would require a different organization
(e.g. moving or duplicating the calls to window-splittable-p outside of
split-window-sensibly).  Not worth the trouble.


        Stefan

bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> I guess you're right.  It would require a different organization
> (e.g. moving or duplicating the calls to window-splittable-p outside of
> split-window-sensibly).  Not worth the trouble.

I guess this was resolved, so I'm closing this report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/