RE: display-buffer cleverness - how to tame?

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

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

Yes, I read it. No, I don't see any such "step-by-step operative description".
I'm looking at the latest pretest. If you've updated the manual since then, then
no, I haven't read your update.

There is this sentence: "Precisely how `display-buffer' finds or creates a
window depends on the variables described below." And then the variables are
described.

IOW, we say that how it does it what it does depends on the variables. But I
don't see that "how" or even that "what" described in any "step-by-step
operative description".

Sorry; it's not clear to me from reading that doc (or the doc strings).

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

That's fine. The doc strings can point to the doc. But the doc itself is not
very clear, to me. 

You know the code. You have in mind just "how `display-buffer' finds a window to
split and how it tries to split it", but I don't see that explained, and I don't
understand it. Call me dense, if you like.

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

Sounds like you want to argue. Just trying to help. I think "returns" is more
helpful here, but use whatever wording you like.

BTW, I realize now that I misread the doc string for
`split-window-preferred-function'. It says that if the option value is nil...,
and I misread that as saying that if the option value is a function that returns
nil both times it is called by `display-buffer'... Trying to understand the doc
string while reading the code, I mixed things up.

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

Yes, it's there. I can dig out that meaning after several readings. But this
description of `split-height-threshold' is hard to follow:

"If no window is tall enough, or if the value of
this variable is `nil', `display-buffer' tries to split some window
horizontally, subject to restrictions of `split-width-threshold'
(see below).  If splitting horizontally is impossible too,
`display-buffer' splits a window vertically only if it's the only
window on its frame and not the minibuffer window, and only if
`pop-up-windows' is non-`nil'."

If that description is combined with the description of `split-width-threshold',
then yes, it follows that when both are nil then in most cases no window is
split. But it takes some digging to get that.

(The description of `split-width-threshold' is, however, clear.)

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

So `split-window-preferred-function' is now always a function? That would seem
to change quite a lot. 

Looking at the `window.el' code in the pretest, I cannot imagine what the
resulting behavior change will be. Will `window--try-to-split-window' always use
`split-window-preferred-function'? Will the default value of that option then be
some function that calls `window--splittable-p' and takes into account the two
thresholds somehow? Presumably, but just what/how?...

I think I'll wait and see the new code and doc, before trying to figure out the
behavior.
 
>  >>  > 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.

The current (pretest) code has `split-window-preferred-function' = nil. If that
won't be nil, then with what default-value function would I replace it, in order
to "try it" (the new behavior)?

I'll just wait and see what this is all about. It's too difficult to follow at
this point. If my feedback helps, fine; if not, ignore.