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

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

We should document more explicitly how to obtain the window-splitting
behavior for buffer display that existed prior to Emacs 23.  The NEWS
says only this:
 
 "*** display-buffer tries to be smarter when splitting windows.  The
 new option split-window-preferred-function lets you specify your own
 function to pop up new windows.  Its default value
 split-window-sensibly can split a window either vertically or
 horizontally, whichever seems more suitable in the current
 configuration.  You can tune the behavior of split-window-sensibly by
 customizing split-height-threshold and the new option
 split-width-threshold.  Both options now take the value nil to
 inhibit splitting in one direction.  Setting split-width-threshold to
 nil inhibits horizontal splitting and gets you the behavior of Emacs
 22 in this respect.  In any case, display-buffer may now split the
 largest window vertically even when it is not as wide as the
 containing frame."
 
Most of that just describes the new behavior, repeating what is in the
manual.  That's OK, but insufficient for NEWS.
 
The last two sentences are all that is said about how to get the
pre-Emacs 23 behavior, and they speak only about horizontal splitting.
 
Nothing is said about how to get the pre-Emacs 23 behavior for
_choosing which window is split_, and that change is a radical
departure from previous behavior - a change just as important as the
change regarding horizontal splitting.
 
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)))
 
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'.
 
 
 
In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'