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

[Drew Adams]

> IMHO `display-buffer' has to follow (a) changes in display technology
> and (b) user preferences.  (a) implies that code cannot rely 
> upon which window gets split or how that window is split accross future 
> versions of Emacs.  (b) implies that code using `display-buffer' must
> be aware of user preferences.
> 
> If coders want precise control, they should use `set-window-buffer'.
> 
> The `not-this-window' argument should be used with caution because it
> already now overrides user preferences wrt to `display-buffer'.
> I think that only if the user does not specify any preference in 
> `pop-up-frames' or `pop-up-windows', an application should be allowed
> to override that. So we should enhance the semantics of these
> variables first.
> 
> In addition, I think `window-size-fixed' should be handled the way we
> treat dedicated windows.  That is, when this is non-nil for a 
> particular window, it should inhibit that `display-buffer' splits
> that window.  But only the value `t' should inhibit that the window
> can be resized manually.  Thus an application can set
> `window-size-fixed' to some non-nil, non-t value to avoid that the
> window gets split and/or resized by `display-buffer'.
> 
> 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.

The more you guys play with this, changing behavior, the more users and
programmers have to jump through hoops to keep up with the changes. Let it be.
At least for a few years. ;-)

Something like `display-buffer' is fundamental, core, ubiquitous. When you mess
with it (in attempts to improve it), you mess with Emacs and Emacs users in
fundamental ways.