(Displaying Buffers): Minor wording fix.

(Choosing Window): `split-height-threshold' can now be nil.
Document `split-width-threshold'.  `pop-up-frames' can have the value
`graphic-only'.

3 files changed, 52 insertions, 12 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5891f611050..cc74a973792 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2008-10-18  Eli Zaretskii  <eliz@gnu.org>
+
+        * windows.texi (Displaying Buffers): Minor wording fix.
+        (Choosing Window): `split-height-threshold' can now be nil.
+        Document `split-width-threshold'.  `pop-up-frames' can have the
+        value `graphic-only'.
+
 2008-10-17  Eli Zaretskii  <eliz@gnu.org>
 
         * os.texi (Startup Summary): Document `before-init-time' and
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6cc5d03206f..09cfff227d4 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -794,7 +794,7 @@ See the preceding section for
 @ifnottex
 @xref{Buffers and Windows}, for
 @end ifnottex
-low-level functions that give you more precise control.  All of these
+low-level primitives that give you more precise control.  All of these
 functions work by calling @code{set-window-buffer}.
 
   Do not use the functions in this section in order to make a buffer
@@ -951,6 +951,16 @@ Precisely how @code{display-buffer} finds or creates a window depends on
 the variables described below.
 @end deffn
 
+@defun split-window-preferred-function window
+This variable specifies how to split a window.  Its value, if
+non-@code{nil}, should be a function of one argument, which is a
+window.  If this variable specifies a function, @code{display-buffer}
+will call it with one or more candidate windows when it looks for a
+window to split.  If the argument @var{window} fits, the function is
+expected to split it and return a new window.  If the function returns
+@code{nil}, then @var{window} will not be split.
+@end defun
+
 @defopt display-buffer-reuse-frames
 If this variable is non-@code{nil}, @code{display-buffer} searches
 existing frames for a window displaying the buffer.  If the buffer is
@@ -964,16 +974,31 @@ variables, described below.
 @defopt pop-up-windows
 This variable controls whether @code{display-buffer} makes new windows.
 If it is non-@code{nil} and there is only one window, then that window
-is split.  If it is @code{nil}, then @code{display-buffer} does not
-split the single window, but uses it whole.
+is split vertically.  If it is @code{nil}, then @code{display-buffer}
+does not split the single window, but uses it whole.
 @end defopt
 
 @defopt split-height-threshold
-This variable determines when @code{display-buffer} may split a window,
-if there are multiple windows.  @code{display-buffer} always splits the
-largest window if it has at least this many lines.  If the largest
-window is not this tall, it is split only if it is the sole window and
-@code{pop-up-windows} is non-@code{nil}.
+This variable determines when @code{display-buffer} may split a window
+vertically, if there are multiple windows.  If the value is a number,
+@code{display-buffer} splits the largest window if it has at least
+this many lines.  If the largest window is not this tall, or if the
+value of this variable is @code{nil}, @code{display-buffer} tries to
+split some window horizontally, subject to restrictions of
+@code{split-width-threshold} (see below).  If splitting horizontally
+is impossible, @code{display-buffer} will split a window vertically
+only if it's the only window on its frame and not the minibuffer
+window, and only if @code{pop-up-windows} is non-@code{nil}.
+Otherwise, @code{display-buffer} uses one of the existing windows.
+@end defopt
+
+@defopt split-width-threshold
+This variable determines when @code{display-buffer} may split a window
+horizontally.  If the value is a number, @code{display-buffer} may
+split a window if it has at least this many columns.  If the value of
+this variable is @code{nil}, @code{display-buffer} will not split any
+windows horizontally.  (It still might split some window vertically,
+though, see above.)
 @end defopt
 
 @defopt even-window-heights
@@ -989,10 +1014,13 @@ will be left alone.
 @defopt pop-up-frames
 This variable controls whether @code{display-buffer} makes new frames.
 If it is non-@code{nil}, @code{display-buffer} looks for an existing
-window already displaying the desired buffer, on any visible frame.  If
-it finds one, it returns that window.  Otherwise it makes a new frame.
-The variables @code{pop-up-windows} and @code{split-height-threshold} do
-not matter if @code{pop-up-frames} is non-@code{nil}.
+window already displaying the desired buffer, on any visible frame.
+If it finds one, it returns that window.  Otherwise it makes a new
+frame, unless the variable's value is @code{graphic-only} and the
+selected frame is not on a graphic display.  The variables
+@code{pop-up-windows}, @code{split-height-threshold}, and
+@code{split-width-threshold} do not matter if @code{pop-up-frames} is
+non-@code{nil}.
 
 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
 splits a window or reuses one.
diff --git a/etc/NEWS b/etc/NEWS
index 58c4388fba2..b2e73354061 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1221,16 +1221,21 @@ Emacs initialization.
 
 ** Changes affecting display-buffer
 
++++
 *** New value nil for split-height-threshold inhibits vertical splitting
 unless there's no other window.
 
++++
 *** New option split-width-threshold controls horizontal splitting.
 
++++
 *** A window can be split horizontally even when it's not full-width.
 
++++
 *** New option split-window-preferred-function can be set to a function
 to override the default splitting mechanism of display-buffer.
 
++++
 *** If pop-up-frames has the value `graphic-only', display-buffer only
 makes a separate frame on graphic displays.