; Fix last change

* etc/NEWS:
* doc/lispref/windows.texi (Choosing Window Options):
* doc/emacs/windows.texi (Window Choice): Improve documentation of
'split-window-preferred-direction'.

doc/emacs/windows.texi

@@ -519,6 +519,8 @@ selected frame, and display the buffer in that new window.
 @vindex split-height-threshold
 @vindex split-width-threshold
 @vindex split-window-preferred-direction
+@cindex portrait frame
+@cindex landscape frame
 The split can be either vertical or horizontal, depending on the
 variables @code{split-height-threshold} and
 @code{split-width-threshold}.  These variables should have integer
@@ -528,8 +530,14 @@ window's height, the split puts the new window below.  Otherwise, if
 split puts the new window on the right.  If neither condition holds,
 Emacs tries to split so that the new window is below---but only if the
 window was not split before (to avoid excessive splitting).  Whether
-Emacs tries first to split vertically or horizontally, is
-determined by the value of @code{split-window-preferred-direction}.
+Emacs tries first to split vertically or horizontally when both
+conditions hold is determined by the value of
+@code{split-window-preferred-direction}.  Its default is @code{longest},
+which means to split vertically if the window's frame is taller than it
+is wide (a @dfn{portrait} frame), and split horizontally if its wider
+than it's tall (a @dfn{landscape} frame).  The values @code{vertical}
+and @code{horizontal} always prefer, respectively, the vertical or the
+horizontal split.
 
 @item
 Otherwise, display the buffer in a window previously showing it.

doc/lispref/windows.texi

@@ -4122,16 +4122,19 @@ window.  If @var{window} cannot be split, it returns @code{nil}.  If
 @var{window} is omitted or @code{nil}, it defaults to the selected
 window.
 
-This function obeys the usual rules that determine when a window may
-be split (@pxref{Splitting Windows}).  It first tries to split by
-placing the new window below, subject to the restriction imposed by
-@code{split-height-threshold} (see below), in addition to any other
-restrictions.  If that fails, it tries to split by placing the new
-window to the right, subject to @code{split-width-threshold} (see
-below).  If that also fails, and the window is the only window on its
-frame, this function again tries to split and place the new window
-below, disregarding @code{split-height-threshold}.  If this fails as
-well, this function gives up and returns @code{nil}.
+This function obeys the usual rules that determine when a window may be
+split (@pxref{Splitting Windows}).  It first tries either a vertical
+split by placing the new window below, subject to the restriction
+imposed by @code{split-height-threshold} (see below), or a horizontal
+split that places the new window to the right, subject to
+@code{split-width-threshold}, in addition to any other restrictions.
+Whether it tries first to split vertically or horizontally depends on
+the value of the user option @code{split-window-preferred-direction}.
+If splitting along the first dimension fails, it tries to split along
+the other dimension.  If that also fails, and the window is the only
+window on its frame, this function again tries to split and place the
+new window below, disregarding @code{split-height-threshold}.  If this
+fails as well, this function gives up and returns @code{nil}.
 @end defun
 
 @defopt split-height-threshold
@@ -4150,6 +4153,18 @@ window has at least that many columns.  If the value is @code{nil},
 that means not to split this way.
 @end defopt
 
+@defopt split-window-preferred-direction
+This variable determines the first dimension along which
+@code{split-window-sensibly} tries to split the window, if the window
+could be split both vertically and horizontally, as determined by the
+values of @code{split-height-threshold} and
+@code{split-width-threshold}.  The default value is @code{longest},
+which means to split vertically if the height of the window's frame is
+greater or equal to its width, and horizontally otherwise.  The values
+@code{vertical} and @code{horizontal} specify the direction in which to
+attempt the first split.
+@end defopt
+
 @defopt even-window-sizes
 This variable, if non-@code{nil}, causes @code{display-buffer} to even
 window sizes whenever it reuses an existing window, and that window is

etc/NEWS

@@ -416,11 +416,20 @@ for which you can use '(category . tex-shell)'.
 
 +++
 *** New user option 'split-window-preferred-direction'.
-Users can now choose in which direction Emacs tries to split first:
-vertically or horizontally.  The new default is to prefer to split
-horizontally if the frame is landscape and vertically if it is portrait.
-You can customize this option to 'vertical' to restore Emacs's old
-behavior of always preferring vertical splits.
+Functions called by 'display-buffer' split the selected window when they
+need to create a new window.  A window can be split either vertically,
+one below the other, or horizontally, side by side.  This new option
+determines which direction will be tried first, when both directions are
+possible according to the values of 'split-width-threshold' and
+'split-height-threshold'.  The default value is 'longest', which means
+to prefer to split horizontally if the window's frame is a "landscape"
+frame, and vertically if it is a "portrait" frame.  (A frame is
+considered to be "portrait" if its vertical dimension in pixels is
+greater or equal to its horizontal dimension, otherwise it's considered
+to be "landscape".)  Previous versions of Emacs always tried to split
+vertically first, so to get previous behavior, you can customize this
+option to 'vertical'.  The value 'horizontal' always prefers the
+horizontal split.
 
 +++
 *** New argument INDIRECT for 'get-buffer-window-list'.