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