Re: display-buffer cleverness - how to tame?

[martin rudalics <rudalics@gmx.at>]

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

You asked why Emacs 23 behaves differently, so I tried to explain its
behavior in terms of what I understand about the behavior of Emacs 22.

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

 >> If that call fails to provide a suitable window, it gets called
 >> again with the least recently used window
 >
 > On the same frame, presumably (?).

Yes.

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

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

Which doc-string?  An unconditional phrase like "it will split a window"
should not appear anywhere in the text.

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

I didn't understand your questions.  In any case bear in mind that
`display-buffer' _tries_ to split a window.  If it cannot split a window
for whatever reason it doesn't split it.  The manual states all reasons
why a window cannot 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,
 >
 > Is that stated somewhere?

In the manual.

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

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

martin