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