display-buffer cleverness - how to tame?

display-buffer cleverness - how to tame?

[Drew Adams]

I'm sure the new display-buffer behavior is an improvement in some way, but it
seems too clever by half, at least in one context I have.

I'm not suggesting the smarter behavior should be reverted (I'd have to
understand it first, to be able to suggest that ;-)). I just want to know which
settings I need, to get back the previous behavior for some code I have that
(apparently) depends on it. The code works with Emacs 20-22, but breaks with
Emacs 23. Because of a different bug (#3081), which was recently fixed, I
couldn't see this bug before now.

I haven't spent a lot of time investigating, but the problem seems to be that
display-buffer now tries to split the largest window. I can see that there are
several variables that control display-buffer, but could someone please point
out the settings that will restore the previous (Emacs 22) unclever behavior. 

In particular, I have two windows, left and right, with the left one wider and
selected when I call display-buffer. The behavior I want is for the right,
narrower window to be split (vertically). Instead, it is the left, wider window
that gets split (vertically).

Thx.

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > I haven't spent a lot of time investigating, but the problem seems to be that
 > display-buffer now tries to split the largest window.

In Emacs 22 `display-buffer' tries to split the largest window first
and, if that fails, the least recently used window.  This behavior is
unchanged in Emacs 23.

 > In particular, I have two windows, left and right, with the left one wider and
 > selected when I call display-buffer. The behavior I want is for the right,
 > narrower window to be split (vertically). Instead, it is the left, wider window
 > that gets split (vertically).

In Emacs 22 `display-buffer' didn't try to split the largest window
vertically when it was not full-width.  No such restrictions applied for
the least recently used window.  In Emacs 23 the largest window can get
split even when it's not full-width.

To get the old behavior back in your case it will be best to write your
own `split-window-preferred-function' just as we're currently trying to
do for `dired-pop-to-buffer'.  This will let you specify explicitly
which window `display-buffer' should try to split and whether it should
split it vertically or horizontally.

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

> To get the old behavior back in your case it will be best to 
> write your own `split-window-preferred-function' just as we're
> currently trying to do for `dired-pop-to-buffer'.  This will
> let you specify explicitly which window `display-buffer' should
> try to split and whether it should
> split it vertically or horizontally.

It's a joke, right?  Emacs adding DWIM now means that if you want the simple,
straightforward behavior of old you need to write it yourself?

I'd sooner copy the Emacs 22 `display-buffer' code and just use that, except
that it's in C. ;-)

You are not making it easier for users (which includes Emacs-Lisp users)...

Re: display-buffer cleverness - how to tame?

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> It's a joke, right?  Emacs adding DWIM now means that if you want the simple,
> straightforward behavior of old you need to write it yourself?

If almost nobody actually does, then that's not a problem, right?

-Miles

-- 
Custard, n. A vile concoction produced by a malevolent conspiracy of the hen,
the cow, and the cook.

RE: display-buffer cleverness - how to tame?

[Drew Adams]

> > It's a joke, right?  Emacs adding DWIM now means that if 
> > you want the simple, straightforward behavior of old you
> > need to write it yourself?
> 
> If almost nobody actually does, then that's not a problem, right?

That's sorry logic. The fact (unproven, BTW) that few people will actually go to
that trouble is no proof that almost nobody would appreciate such a result.

The fact that few people actually build an energy-efficient car themselves from
scratch is hardly proof that no one would appreciate such a car.

If the new `display-buffer' approach is so complex that just describing a simple
way to get back the old behavior is too difficult (even for the implementor!),
then, yes, I think we have a problem.

Introduce cleverness, if you must, but please give users a simple way to return
to the simple. "Write your own Emacs, if you don't like the new, improved
version" is one, knee-jerk response. It's not a very good response, IMO.

By a simple way, I mean, for example, just customizing a user option or two -
not implementing complex functions. It is merely punting to provide just a
function-valued option `do-it-yourself'. When DWIM -> DYI, something is amiss.

Re: display-buffer cleverness - how to tame?

[Samuel Bronson]

On Mon, May 4, 2009 at 11:49 AM, Drew Adams <drew.adams@oracle.com> wrote:
> By a simple way, I mean, for example, just customizing a user option or two -
> not implementing complex functions. It is merely punting to provide just a
> function-valued option `do-it-yourself'. When DWIM -> DYI, something is amiss.

Well, it's pretty close though. If you do that AND define the very
function you would need to set the variable to reference AND add the
necessary defcustom magic to allow the user to just pick the old
function from a drop-down list, that should be good, no?

Of course, preferably the function should be pretty short, too -- if
the old behaviour was in fact simple. (And, scrolling down, I see that
this is apparently not the case.)

And that's just for user customization of split-window -- for Emacs
lisp programs, it sounds like there should probably be some
more-parametrized function.

Re: display-buffer cleverness - how to tame?

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>> > It's a joke, right?  Emacs adding DWIM now means that if 
>> > you want the simple, straightforward behavior of old you
>> > need to write it yourself?
>>
>> If almost nobody actually does, then that's not a problem, right?
>
> That's sorry logic. The fact (unproven, BTW) that few people will
> actually go to that trouble is no proof that almost nobody would
> appreciate such a result.

No, what I meant was, "if almost nobody wants the ... behavior of old,
then [the non-trivial burden of recreating it] is not a problem, right?"

[As Stefan pointed out , the old behavior was really no simpler, so
using a term like "simple, straightforward behavior" to describe it, is
just rhetoric.]

Granted those people who actually notice the difference may have become
accustomed to the old behavior, however arbitrary, and may desire it for
that reason.

-Miles

-- 
Cannon, n. An instrument employed in the rectification of national boundaries.

Re: display-buffer cleverness - how to tame?

[Stefan Monnier]

> It's a joke, right?  Emacs adding DWIM now means that if you want the simple,
> straightforward behavior of old you need to write it yourself?

I think you're slightly exaggerating here: the behavior you seem to want
(i.e. split vertically the smaller window, just because it happens to
be the LRU window and because the largest is not full-width), is pretty
far from "straightforward".
It was at least as magical as the current behavior.  It just happened to
work well in one of your cases, by accident.


        Stefan

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > It's a joke, right?

No Drew, it's serious.

 > Emacs adding DWIM now means that if you want the simple,
 > straightforward behavior of old you need to write it yourself?

It's not about adding DWIM.  Let's have a look at "the simple,
straightforward behavior of old": You apparently have a frame with two
side-by-side windows and `pop-up-frames' bound to nil (IIRC
`pop-up-frames' is usually non-nil on your Emacs).  The left window is
the larger one and the right window the least recently used one.

Emacs 22 first tries to split the larger (left) window and fails to do
so because the window is not full-width.  Then Emacs tries to split the
least recently used (right) one and succeeds.  I suppose you were not
aware of this since otherwise you wouldn't have written (in your first
mail on this subject) "the problem seems to be that display-buffer now
tries to split the largest window" where "now" apparently means "Emacs
23".  The difference is that with Emacs 23 `display-buffer' tries to
split the largest window _and_ succeeds in doing so.

So basically you wrote some code that (1) relied on some undocumented
behavior of `display-buffer', and (2) would have failed to DTRT with
more than two windows on your frame or the window on the right not being
the least recently used one.

 > I'd sooner copy the Emacs 22 `display-buffer' code and just use that, except
 > that it's in C. ;-)

You could try getting the version distributed with XEmacs.  It's in
Elisp and should still exhibit the old behavior ;-)

 > You are not making it easier for users (which includes Emacs-Lisp users)...

The present code is more fully documented.  So I hopefully made it
easier for users (which includes Emacs-Lisp users) to complain ...

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

>  > Emacs adding DWIM now means that if you want the simple,
>  > straightforward behavior of old you need to write it yourself?
> 
> It's not about adding DWIM.  Let's have a look at "the simple,
> straightforward behavior of old": You apparently have a frame with two
> side-by-side windows and `pop-up-frames' bound to nil (IIRC
> `pop-up-frames' is usually non-nil on your Emacs).  The left window is
> the larger one and the right window the least recently used one.
> 
> Emacs 22 first tries to split the larger (left) window and fails to do
> so because the window is not full-width.  Then Emacs tries to split the
> least recently used (right) one and succeeds.  I suppose you were not
> aware of this

Correct; I was not aware of the details behind the Emacs 22 "magic", as Stefan
put it. Thanks for the explanation.

> since otherwise you wouldn't have written (in your first
> mail on this subject) "the problem seems to be that display-buffer now
> tries to split the largest window" where "now" apparently means "Emacs
> 23".  The difference is that with Emacs 23 `display-buffer' tries to
> split the largest window _and_ succeeds in doing so.

Thanks for that explanation also. You might consider mentioning that change in
the NEWS (in those terms or similar terms) - your call.

The question I have now is how to impose, in a particular call to
`display-buffer', *not* splitting a window if it is not full-width? That is, how
to reinstate that pre-Emacs 23 splitting criterion (temporarily)?

I'd also like to know how to tell `display-buffer' not to split the selected
window, and how to tell it specifically which window to split. Those approaches
would also solve the problem I see here (in alternative ways), and that
knowledge would be generally helpful (to me, at least).

> So basically you wrote some code that (1) relied on some undocumented
> behavior of `display-buffer',

Yes, I mentioned that.

Because the behavior was undocumented, it was magic, and more or less
take-it-or-leave-it. Replacing it with different magic is OK, but let's document
that, so the magic trick is exposed.

And let's provide simple ways to control the behavior, other than
`define-your-own'.

> and (2) would have failed to DTRT with
> more than two windows on your frame or the window on the 
> right not being the least recently used one.

Which is not a problem here - that cannot be the case in my context. But it is
good to know.

>  > You are not making it easier for users (which includes 
>  > Emacs-Lisp users)...
> 
> The present code is more fully documented.  So I hopefully made it
> easier for users (which includes Emacs-Lisp users) to complain ...

That's good. Maybe there are still a few things that could be explained? My
questions above are a start.

Martin, I do appreciate the work you've done wrt behavior involving windows,
BTW, as I think you know. Much of that work has in fact been clearing up and
taming existing magical, take-it-or-leave-it behavior. I'm thinking, for
instance, of the work you did around quitting help and view mode.

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > The question I have now is how to impose, in a particular call to
 > `display-buffer', *not* splitting a window if it is not full-width? That is, how
 > to reinstate that pre-Emacs 23 splitting criterion (temporarily)?

Emacs 22 did split a non-full-width window vertically and from your
previous posts you even relied on and wanted that behavior.  The only
new twist is that Emacs 23 may split the non-full-width largest window
even when it's not the least recently used one.

 > I'd also like to know how to tell `display-buffer' not to split the selected
 > window, and how to tell it specifically which window to split. Those approaches
 > would also solve the problem I see here (in alternative ways), and that
 > knowledge would be generally helpful (to me, at least).

That's what `split-window-preferred-function' is all about.  It gets
called with the window to split and you can temporarily bind your own
function to that.  That function would check if the window to split is
the selected one and, if that is the case, split another one instead
provided such a window exists.  BTW, your example is a second reason why
`split-window-preferred-function' should be called with an argument, so
I plan to leave the current calling convention alone.

 >> and (2) would have failed to DTRT with
 >> more than two windows on your frame or the window on the
 >> right not being the least recently used one.
 >
 > Which is not a problem here - that cannot be the case in my context. But it is
 > good to know.

If you as designer are in full control of the context then why do you
rely on `display-buffer' in the first place?  The whole idea of
`display-buffer' is to shift control to the users' customizations ...

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

>  > The question I have now is how to impose, in a particular call to
>  > `display-buffer', *not* splitting a window if it is not 
>  > full-width? That is, how
>  > to reinstate that pre-Emacs 23 splitting criterion (temporarily)?
> 
> Emacs 22 did split a non-full-width window vertically and from your
> previous posts you even relied on and wanted that behavior.  The only
> new twist is that Emacs 23 may split the non-full-width largest window
> even when it's not the least recently used one.

So the question is, then, how to get Emacs 23 to not split that (non-full-width
largest) window if it is not the lru window?

>  > I'd also like to know how to tell `display-buffer' not to 
>  > split the selected window, and how to tell it specifically
>  > which window to split. Those approaches would also solve the
>  > problem I see here (in alternative ways), and that
>  > knowledge would be generally helpful (to me, at least).
> 
> That's what `split-window-preferred-function' is all about.  It gets
> called with the window to split and you can temporarily bind your own
> function to that.  That function would check if the window to split is
> the selected one and, if that is the case, split another one instead
> provided such a window exists.  BTW, your example is a second 
> reason why `split-window-preferred-function' should be called with an 
> argument, so I plan to leave the current calling convention alone.

OK, thanks.

However, the doc string for `split-window-preferred-function' is not clear (to
me). First, this sentence is not grammatically correct; I can't understand it:

"If non-nil, a function called with a window as single argument
supposed to split that window and return the new window."

That seems to say that the window argument is supposed to split itself, or
something like that.

From your description above, the function decides, based on a window passed as
arg, which window to split, and then splits the window it chooses. Is that
correct?

Why is a particular window passed as arg, if the choice of which window to split
is up to the function? Is there some usual interpretation/use of that window
arg? When `display-buffer' calls `split-window-preferred-function', which window
does it pass as arg? What is the role/meaning of that window; how does
`display-buffer' pick it? You say the function is called "with the window to
split", but what does that mean, if it is the function itself that decides which
window to split (and splits it)?

This info seems to be missing. At least it's not clear to me.

>  >> and (2) would have failed to DTRT with
>  >> more than two windows on your frame or the window on the
>  >> right not being the least recently used one.
>  >
>  > Which is not a problem here - that cannot be the case in 
>  > my context. But it is good to know.
> 
> If you as designer are in full control of the context then why do you
> rely on `display-buffer' in the first place?  The whole idea of
> `display-buffer' is to shift control to the users' customizations ...

I'm sure you don't want the details of the code. If you do, we can take it off
the list. And yes, there are no doubt alternative ways to code what I need.

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > So the question is, then, how to get Emacs 23 to not split that (non-full-width
 > largest) window if it is not the lru window?

Exact.

 > However, the doc string for `split-window-preferred-function' is not clear (to
 > me). First, this sentence is not grammatically correct; I can't understand it:
 >
 > "If non-nil, a function called with a window as single argument
 > supposed to split that window and return the new window."
 >
 > That seems to say that the window argument is supposed to split itself, or
 > something like that.

Well, even an Emacs window won't split itself, but this part must be
rewritten anyway.

 >>From your description above, the function decides, based on a window passed as
 > arg, which window to split, and then splits the window it chooses. Is that
 > correct?

The function should split the window passed as arg but no one will ask
whether it really split that window.  As a matter of fact, the function
may do anything it wants as long as it returns a live window.

 > Why is a particular window passed as arg, if the choice of which window to split
 > is up to the function?

Because the standard (not user-written) functions will try to split the
window passed as arg.

 > Is there some usual interpretation/use of that window
 > arg?

The interpretation is "this is one of the windows Emacs 22 tried to split".

 > When `display-buffer' calls `split-window-preferred-function', which window
 > does it pass as arg?

In a first call the largest window of the selected frame, in the second
call the least recently used one.

 > What is the role/meaning of that window; how does
 > `display-buffer' pick it? You say the function is called "with the window to
 > split", but what does that mean, if it is the function itself that decides which
 > window to split (and splits it)?

Up to Emacs 22 the identity of the window to split was hardcoded.  The
present code gives you a way to override that while keeping most of the
historic details.  I dislike the get-largest/LRU-window mumbo jumbo and
rather have `split-window-preferred-function' decide which window(s) to
split ...

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

>  > Is there some usual interpretation/use of that window arg?
> 
> The interpretation is "this is one of the windows Emacs 22 
> tried to split".

Is that the way it will be explained in the doc, by referring to Emacs 22's
(undocumented, magic) behavior?

I think it should be documented that `split-window-preferred-function', if
non-nil, is called by `display-buffer' potentially twice, to determine the
window (if any) to split. The first time, it is passed the largest window. Only
if it returns nil is it called a second time, with the lru window as argument.

Without this info, I don't think users will know what
`split-window-preferred-function' is about, hence how to code a suitable
function for it.

The doc string says that if `split-window-preferred-function' returns nil both
times, then `display-buffer' splits the window that respects the values of
`split-height-threshold' and `split-width-threshold'.

What if more than one window respects those values? Among which windows does
`display-buffer' choose, and how does it choose one of them, if more than one
respects those values? And what does it do if no window respects those values?
This info is missing, AFAICT.

It sounds as if no matter how `split-window-preferred-function' is defined,
`display-buffer' will split a window. Is that correct? That's what the doc
string seems to say - either `split-window-preferred-function' splits a window
or `display-buffer' splits one that respects `split-height-threshold' and
`split-width-threshold'.

If that's not true, then (besides fixing the doc), how can
`split-window-preferred-function' prevent window splitting altogether?

(Thanks for the other explanations. Hopefully, this info will make it into the
doc eventually.)

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 >> The interpretation is "this is one of the windows Emacs 22
 >> tried to split".
 >
 > Is that the way it will be explained in the doc, by referring to Emacs 22's
 > (undocumented, magic) behavior?

No.  I can't do that because I don't completely understand the behavior
of Emacs 22 in this regard.

 > I think it should be documented that `split-window-preferred-function', if
 > non-nil, is called by `display-buffer' potentially twice, to determine the
 > window (if any) to split. The first time, it is passed the largest window. Only
 > if it returns nil is it called a second time, with the lru window as argument.
 >
 > Without this info, I don't think users will know what
 > `split-window-preferred-function' is about, hence how to code a suitable
 > function for it.

I submitted my latest version of this today to the bug#3142 thread.  The
new doc-string of `split-window-preferred-function' reads as:

(defcustom split-window-preferred-function 'split-window-sensibly
   "Function called by `display-buffer' to split a window.
The function is called with a window as single argument and is
supposed to either split that window and return the new window or
return nil if the window can (or shall) not be split.

The default is to split the window \"sensibly\".  This calls the
function `split-window-sensibly' which tries to split the window
in a way which seems most suitable.  A second standard option is
\"vertically\" to split the window into two windows one above the
other.  The third standard option is \"horizontally\" which tries
to split the window into two windows side by side.  All three
standard options examine the values of `split-height-threshold'
and/or `split-width-threshold' before they apply the split.

If you set this to any other function, bear in mind that it may
be called two times: The argument of the first call is the
largest window on its frame.  If that call fails to provide a
suitable window, it gets called again with the least recently
used window as argument.  If neither of these calls produces a
suitable window, `display-buffer' will use an existing one to
display its buffer.

The window selected at the time `display-buffer' was invoked is
selected when `split-window-preferred-function' gets called.
Hence you can compare WINDOW with the value of `selected-window'
if you always want to split the selected window instead of WINDOW
or if you never want to split the currently selected window."
   ...

 > The doc string says that if `split-window-preferred-function' returns nil both
 > times, then `display-buffer' splits the window that respects the values of
 > `split-height-threshold' and `split-width-threshold'.
 >
 > What if more than one window respects those values? Among which windows does
 > `display-buffer' choose, and how does it choose one of them, if more than one
 > respects those values? And what does it do if no window respects those values?
 > This info is missing, AFAICT.

It usually says "tries to split" so if the window can't be split it
won't be split.

 > It sounds as if no matter how `split-window-preferred-function' is defined,
 > `display-buffer' will split a window. Is that correct?

No.  There's no window splitting when `pop-up-windows' is nil.  Usually
there's no window splitting either when both `split-height-threshold'
and `split-width-threshold' are nil, but that can be overridden by
writing a `split-window-preferred-function' which simply disregards
these variables' values.

 > That's what the doc
 > string seems to say - either `split-window-preferred-function' splits a window
 > or `display-buffer' splits one that respects `split-height-threshold' and
 > `split-width-threshold'.

With the new code any splitting will be done exclusively by
`split-window-preferred-function'.

 > If that's not true, then (besides fixing the doc), how can
 > `split-window-preferred-function' prevent window splitting altogether?

With the new code by always returning nil.

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

>  >> The interpretation is "this is one of the windows Emacs 22
>  >> tried to split".
>  >
>  > Is that the way it will be explained in the doc, by 
>  > referring to Emacs 22's (undocumented, magic) behavior?
> 
> No.  I can't do that because I don't completely understand 
> the behavior of Emacs 22 in this regard.

Right. So the real question is how will it be explained? My point was that there
should be no need to refer to Emacs 22.

>  > I think it should be documented that 
>  > `split-window-preferred-function', if non-nil, is called by
>  > `display-buffer' potentially twice, to determine the
>  > window (if any) to split. The first time, it is passed the 
>  > largest window. Only if it returns nil is it called a
>  > second time, with the lru window as argument.
>  >
>  > Without this info, I don't think users will know what
>  > `split-window-preferred-function' is about, hence how to 
>  > code a suitable function for it.
> 
> I submitted my latest version of this today to the bug#3142 
> thread.  The new doc-string of `split-window-preferred-function'
> reads as:
> 
> (defcustom split-window-preferred-function 'split-window-sensibly
>    "Function called by `display-buffer' to split a window.
> The function is called with a window as single argument and is
> supposed to either split that window and return the new window or
> return nil if the window can (or shall) not be split.
> 
> The default is to split the window \"sensibly\".  This calls the
> function `split-window-sensibly' which tries to split the window
> in a way which seems most suitable.  A second standard option is
> \"vertically\" to split the window into two windows one above the
> other.  The third standard option is \"horizontally\" which tries
> to split the window into two windows side by side.  All three
> standard options examine the values of `split-height-threshold'
> and/or `split-width-threshold' before they apply the split.

To what do those quoted "standard option"s refer? Are they user options?

Why refer to something as "standard" and yet quote it as if it has some
non-standard meaning? I really don't know what those strings "sensibly",
"vertically", and "horizontally" mean here.

> If you set this to any other function, bear in mind that it may
> be called two times: The argument of the first call is the
> largest window on its frame.

But which frame is used? How, if at all, does that unspecified frame relate to
the `display-buffer' FRAME arg?

> If that call fails to provide a suitable window, it gets called
> again with the least recently used window

On the same frame, presumably (?).

> as argument.  If neither of these calls produces

"returns" would be better than "produces". It is the return value that is
examined.

> a suitable window, `display-buffer' will use an existing one to
> display its buffer.

It will display the buffer in an existing window? The previous doc string said
that it will split a window to do the displaying.

> The window selected at the time `display-buffer' was invoked is
> selected when `split-window-preferred-function' gets called.
> Hence you can compare WINDOW with the value of `selected-window'
> if you always want to split the selected window instead of WINDOW
> or if you never want to split the currently selected window."
>    ...
> 
>  > The doc string says that if `split-window-preferred-function'
>  > returns nil both times, then `display-buffer' splits the
>  > window that respects the values of `split-height-threshold'
>  > and `split-width-threshold'.
>  >
>  > What if more than one window respects those values? Among 
>  > which windows does `display-buffer' choose, and how does it
>  > choose one of them, if more than one respects those values?
>  > And what does it do if no window respects those values?
>  > This info is missing, AFAICT.
> 
> It usually says "tries to split" so if the window can't be split it
> won't be split.

I don't follow. I don't think that answers any of those questions.

>  > It sounds as if no matter how 
>  > `split-window-preferred-function' is defined,
>  > `display-buffer' will split a window. Is that correct?
> 
> No.  There's no window splitting when `pop-up-windows' is 
> nil. Usually there's no window splitting either when both
> `split-height-threshold' and `split-width-threshold' are nil,

Is that stated somewhere?

> but that can be overridden by writing a
> `split-window-preferred-function' which simply disregards
> these variables' values.
> 
>  > That's what the doc string seems to say - either 
>  > `split-window-preferred-function' splits a window
>  > or `display-buffer' splits one that respects 
>  > `split-height-threshold' and `split-width-threshold'.
> 
> With the new code any splitting will be done exclusively by
> `split-window-preferred-function'.

Ah, OK. That would explain the doc string change from saying that
`display-buffer' will split to saying that it will display in an existing window
(see above). Is the new behavior you describe in the pretest code, or in a later
bug fix?

>  > If that's not true, then (besides fixing the doc), how can
>  > `split-window-preferred-function' prevent window splitting 
>  > altogether?
> 
> With the new code by always returning nil.

OK. I guess I'll need to try the new behavior, after your recent changes, before
trying to fix my code to make use of the new `display-buffer'.

Thanks for the clarifications.

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > Right. So the real question is how will it be explained? My point was that there
 > should be no need to refer to Emacs 22.

You asked why Emacs 23 behaves differently, so I tried to explain its
behavior in terms of what I understand about the behavior of Emacs 22.

 >> If you set this to any other function, bear in mind that it may
 >> be called two times: The argument of the first call is the
 >> largest window on its frame.
 >
 > But which frame is used? How, if at all, does that unspecified frame relate to
 > the `display-buffer' FRAME arg?

Did you ever read section 28.8 of the Elisp manual?  It gives you a
step-by-step operative description of how `display-buffer' finds a
window to split and how it tries to split it.  The various doc-strings
cannot provide that information since I would have to repeat the entire
process of how to find a window for splitting over and over for each
variable and function involved.

 >> If that call fails to provide a suitable window, it gets called
 >> again with the least recently used window
 >
 > On the same frame, presumably (?).

Yes.

 >> as argument.  If neither of these calls produces
 >
 > "returns" would be better than "produces". It is the return value that is
 > examined.

But usually a new window is created first.

 >> a suitable window, `display-buffer' will use an existing one to
 >> display its buffer.
 >
 > It will display the buffer in an existing window? The previous doc string said
 > that it will split a window to do the displaying.

Which doc-string?  An unconditional phrase like "it will split a window"
should not appear anywhere in the text.

 >>  > The doc string says that if `split-window-preferred-function'
 >>  > returns nil both times, then `display-buffer' splits the
 >>  > window that respects the values of `split-height-threshold'
 >>  > and `split-width-threshold'.
 >>  >
 >>  > What if more than one window respects those values? Among
 >>  > which windows does `display-buffer' choose, and how does it
 >>  > choose one of them, if more than one respects those values?
 >>  > And what does it do if no window respects those values?
 >>  > This info is missing, AFAICT.
 >>
 >> It usually says "tries to split" so if the window can't be split it
 >> won't be split.
 >
 > I don't follow. I don't think that answers any of those questions.

I didn't understand your questions.  In any case bear in mind that
`display-buffer' _tries_ to split a window.  If it cannot split a window
for whatever reason it doesn't split it.  The manual states all reasons
why a window cannot be split.

 >>  > It sounds as if no matter how
 >>  > `split-window-preferred-function' is defined,
 >>  > `display-buffer' will split a window. Is that correct?
 >>
 >> No.  There's no window splitting when `pop-up-windows' is
 >> nil. Usually there's no window splitting either when both
 >> `split-height-threshold' and `split-width-threshold' are nil,
 >
 > Is that stated somewhere?

In the manual.

 >> With the new code any splitting will be done exclusively by
 >> `split-window-preferred-function'.
 >
 > Ah, OK. That would explain the doc string change from saying that
 > `display-buffer' will split to saying that it will display in an existing window
 > (see above). Is the new behavior you describe in the pretest code, or in a later
 > bug fix?

The only user visible change will be that you cannot specify nil as
value of `split-window-preferred-function'.  I'll commit that in a
couple of days.

 >>  > If that's not true, then (besides fixing the doc), how can
 >>  > `split-window-preferred-function' prevent window splitting
 >>  > altogether?
 >>
 >> With the new code by always returning nil.
 >
 > OK. I guess I'll need to try the new behavior, after your recent changes, before
 > trying to fix my code to make use of the new `display-buffer'.

There won't be any substantial change but the one mentioned above, so
you can try it already with the current code.

martin

RE: display-buffer cleverness - how to tame?

[Drew Adams]

>  >> If you set this to any other function, bear in mind that it may
>  >> be called two times: The argument of the first call is the
>  >> largest window on its frame.
>  >
>  > But which frame is used? How, if at all, does that 
>  > unspecified frame relate to the `display-buffer' FRAME arg?
> 
> Did you ever read section 28.8 of the Elisp manual?  It gives you a
> step-by-step operative description of how `display-buffer' finds a
> window to split and how it tries to split it.

Yes, I read it. No, I don't see any such "step-by-step operative description".
I'm looking at the latest pretest. If you've updated the manual since then, then
no, I haven't read your update.

There is this sentence: "Precisely how `display-buffer' finds or creates a
window depends on the variables described below." And then the variables are
described.

IOW, we say that how it does it what it does depends on the variables. But I
don't see that "how" or even that "what" described in any "step-by-step
operative description".

Sorry; it's not clear to me from reading that doc (or the doc strings).

> The various doc-strings cannot provide that information since I
> would have to repeat the entire process of how to find a window
> for splitting over and over for each
> variable and function involved.

That's fine. The doc strings can point to the doc. But the doc itself is not
very clear, to me. 

You know the code. You have in mind just "how `display-buffer' finds a window to
split and how it tries to split it", but I don't see that explained, and I don't
understand it. Call me dense, if you like.

>  >> as argument.  If neither of these calls produces
>  >
>  > "returns" would be better than "produces". It is the 
>  > return value that is examined.
> 
> But usually a new window is created first.

Sounds like you want to argue. Just trying to help. I think "returns" is more
helpful here, but use whatever wording you like.

BTW, I realize now that I misread the doc string for
`split-window-preferred-function'. It says that if the option value is nil...,
and I misread that as saying that if the option value is a function that returns
nil both times it is called by `display-buffer'... Trying to understand the doc
string while reading the code, I mixed things up.

>  >> There's no window splitting when `pop-up-windows' is
>  >> nil. Usually there's no window splitting either when both
>  >> `split-height-threshold' and `split-width-threshold' are nil,
>  >
>  > Is that stated somewhere?
> 
> In the manual.

Yes, it's there. I can dig out that meaning after several readings. But this
description of `split-height-threshold' is hard to follow:

"If no window is tall enough, or if the value of
this variable is `nil', `display-buffer' tries to split some window
horizontally, subject to restrictions of `split-width-threshold'
(see below).  If splitting horizontally is impossible too,
`display-buffer' splits a window vertically only if it's the only
window on its frame and not the minibuffer window, and only if
`pop-up-windows' is non-`nil'."

If that description is combined with the description of `split-width-threshold',
then yes, it follows that when both are nil then in most cases no window is
split. But it takes some digging to get that.

(The description of `split-width-threshold' is, however, clear.)

>  >> With the new code any splitting will be done exclusively by
>  >> `split-window-preferred-function'.
>  >
>  > Ah, OK. That would explain the doc string change from saying that
>  > `display-buffer' will split to saying that it will display 
>  > in an existing window (see above). Is the new behavior you
>  > describe in the pretest code, or in a later bug fix?
> 
> The only user visible change will be that you cannot specify nil as
> value of `split-window-preferred-function'.  I'll commit that in a
> couple of days.

So `split-window-preferred-function' is now always a function? That would seem
to change quite a lot. 

Looking at the `window.el' code in the pretest, I cannot imagine what the
resulting behavior change will be. Will `window--try-to-split-window' always use
`split-window-preferred-function'? Will the default value of that option then be
some function that calls `window--splittable-p' and takes into account the two
thresholds somehow? Presumably, but just what/how?...

I think I'll wait and see the new code and doc, before trying to figure out the
behavior.
 
>  >>  > If that's not true, then (besides fixing the doc), how can
>  >>  > `split-window-preferred-function' prevent window splitting
>  >>  > altogether?
>  >>
>  >> With the new code by always returning nil.
>  >
>  > OK. I guess I'll need to try the new behavior, after your 
>  > recent changes, before trying to fix my code to make use of
>  > the new `display-buffer'.
> 
> There won't be any substantial change but the one mentioned above, so
> you can try it already with the current code.

The current (pretest) code has `split-window-preferred-function' = nil. If that
won't be nil, then with what default-value function would I replace it, in order
to "try it" (the new behavior)?

I'll just wait and see what this is all about. It's too difficult to follow at
this point. If my feedback helps, fine; if not, ignore.

Re: display-buffer cleverness - how to tame?

[martin rudalics]

 > Yes, I read it. No, I don't see any such "step-by-step operative description".
 > I'm looking at the latest pretest. If you've updated the manual since then, then
 > no, I haven't read your update.

This part was written by Eli and I think it's a splendid example of how
to combine the operational description of the buffer displaying process
with the description of the variables that affect this process.  If you
don't see that, then I assure you that I can hardly do any better.

 > There is this sentence: "Precisely how `display-buffer' finds or creates a
 > window depends on the variables described below." And then the variables are
 > described.

At the end of each description Eli explains how the process continues.

 > IOW, we say that how it does it what it does depends on the variables. But I
 > don't see that "how" or even that "what" described in any "step-by-step
 > operative description".
 >
 > Sorry; it's not clear to me from reading that doc (or the doc strings).

Please give us at least one or two concrete examples.

 > Yes, it's there. I can dig out that meaning after several readings. But this
 > description of `split-height-threshold' is hard to follow:
 >
 > "If no window is tall enough, or if the value of
 > this variable is `nil', `display-buffer' tries to split some window
 > horizontally, subject to restrictions of `split-width-threshold'
 > (see below).  If splitting horizontally is impossible too,
 > `display-buffer' splits a window vertically only if it's the only
 > window on its frame and not the minibuffer window, and only if
 > `pop-up-windows' is non-`nil'."
 >
 > If that description is combined with the description of `split-width-threshold',
 > then yes, it follows that when both are nil then in most cases no window is
 > split. But it takes some digging to get that.

As a matter of fact that happened because I tried to be more concrete.
If I omit such details you'll tell me that you miss them :-(

 > So `split-window-preferred-function' is now always a function? That would seem
 > to change quite a lot.

Hardly anything.

 > Looking at the `window.el' code in the pretest, I cannot imagine what the
 > resulting behavior change will be. Will `window--try-to-split-window' always use
 > `split-window-preferred-function'?

Yes, provided the frame is splittable.

 > Will the default value of that option then be
 > some function that calls `window--splittable-p' and takes into account the two
 > thresholds somehow? Presumably, but just what/how?...

The default is now the new function `split-window-sensibly' which has
been split off from `window--try-to-split-window'.

 > I think I'll wait and see the new code and doc, before trying to figure out the
 > behavior.
 >
 >>  >>  > If that's not true, then (besides fixing the doc), how can
 >>  >>  > `split-window-preferred-function' prevent window splitting
 >>  >>  > altogether?
 >>  >>
 >>  >> With the new code by always returning nil.
 >>  >
 >>  > OK. I guess I'll need to try the new behavior, after your
 >>  > recent changes, before trying to fix my code to make use of
 >>  > the new `display-buffer'.
 >>
 >> There won't be any substantial change but the one mentioned above, so
 >> you can try it already with the current code.
 >
 > The current (pretest) code has `split-window-preferred-function' = nil. If that
 > won't be nil, then with what default-value function would I replace it, in order
 > to "try it" (the new behavior)?

`split-window-sensibly'.

martin