RE: display-buffer cleverness - how to tame?

["Drew Adams" <drew.adams@oracle.com>]

>  > 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.)