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.