RE: display-buffer cleverness - how to tame?

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

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