+This variable specifies whether @code{display-buffer} is allowed to
+split (@pxref{Splitting Windows}) an existing window. If this variable
+is non-@code{nil}, @code{display-buffer} tries to split the largest or
+least recently used window on the selected frame. (If the selected
+frame is a minibuffer-only frame, @code{display-buffer} tries to split a
+window on another frame instead.) If this variable is @code{nil} or the
+variable @code{pop-up-frames} (see below) is non-@code{nil},
+@code{display-buffer} does not split any window.
+@end defopt
+
+@defopt split-window-preferred-function
+This variable must specify a function with one argument, which is a
+window. The @code{display-buffer} routines will call this function with
+one or more candidate windows when they look for a window to split. The
+function is expected to split that window and return the new window. If
+the function returns @code{nil}, this means that the argument window
+cannot (or shall not) be split.
+
+The default value of @code{split-window-preferred-function} is the
+function @code{split-window-sensibly} described below. If you
+customize this option, bear in mind that the @code{display-buffer}
+routines may call your function up to two times when trying to split a
+window. The argument of the first call is the largest window on the
+chosen frame (as returned by @code{get-largest-window}). If that call
+fails to return a live window, your function is called a second time
+with the least recently used window on that frame (as returned by
+@code{get-lru-window}).
+
+The function specified by this option may try to split any other window
+instead of the argument window. Note that the window selected at the
+time @code{display-buffer} was invoked is still selected when your
+function is called. Hence, you can split the selected window (instead
+of the largest or least recently used one) by simply ignoring the window
+argument in the body of your function. You can even choose to not split
+any window as long as the return value of your function specifies a live
+window or @code{nil}, but you are not encouraged to do so
+unconditionally. If you want @code{display-buffer} to never split any
+windows, set @code{pop-up-windows} to @code{nil}.