bug#3366: 23.0.94; doc of split-window-preferred-function, display-buffer, etc.

[Drew Adams]

>  > It seems (but I'm not sure this works for all cases) that what is
>  > needed, to ensure that the same window as before is split, 
>  > is to bind `split-window-preferred-function' to something like
>  > this around calls to `display-buffer':
>  > (lambda (w) (eq w (get-lru-window)))
> 
> The function you want might be
> 
> (defun split-window-22 (window)
>    (let ((frame (window-frame window)))
>      (or (and (setq window (get-largest-window frame t))
>            (window-full-width-p window)
>            (window-splittable-p window)
>            (split-window window))
>       (and (setq window (get-lru-window frame t))
>            (window-splittable-p window)
>            (split-window window)))))
> 
> but I wouldn't rely on it.

Thanks for this info, Martin. For the particular code I had in mind the simpler
version I wrote above works, but I understand the difference.

>  > Even if this function is not an exact recipe for all 
>  > cases, something like it should be mentioned, to help users
>  > get back the behavior that existed before the new "smarter"
>  > behavior was introduced. Preferably, Emacs would itself provide
>  > a function that users could use here - a function that would
>  > give precisely the pre-23 behavior in all cases.
>  >
>  > We should also make it clear that if you want the pre-23 
>  > behavior then you will need to wrap not only explicit calls to 
>  > `display-buffer' with a `let' binding this way, but also calls
>  > to things such as `with-output-to-temp-buffer'.
> 
> All people have to do is customize
> `split-window-preferred-function' to that function.

No, I'm talking about code, not a broad user preference setting. Code that
wants, for example, to work with various releases.

But yes, that's my point: We should tell users that they can bind
`split-window-preferred-function' to such a function to get Emacs 22/21/20
behavior wrt window splitting. I suggest we provide such a function, and mention
it in the doc string. If the function you wrote above isn't perfect, it's still
probably pretty good. Bug reports will help perfect it, if need be.