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

[martin rudalics]

>> Also `display-buffer' should call `split-window-preferred-function' at
>> most once.  Calling it with the largest and the LRU window (which may
>> designate one and the same window) appears merely disconcerting.
>
> Agreed.  I have no idea why it's called several times as of now.
> It clearly isn't due to backward compatibility since this is new in
> Emacs 23.

It is due to backward compatibility.  The only new thing here is that
`split-window-preferred-function' can decide whether and how to split
the window.  If it returns nil for the first call it will be called a
second time, though.

martin