-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 specifies 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} splits 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 specifies 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.)