; Improve documentation of window-rotation commands

* lisp/window-x.el (window-layout-rotate-clockwise)
(window-layout-flip-leftright, window-layout-flip-topdown): Doc
fixes.
(rotate-windows-change-selected): Add :version.

* doc/lispref/windows.texi (Recombining Windows): Fix wording,
markup and indexing.

* etc/NEWS: Add key bindings for window-rotation commands and
document 'rotate-windows-change-selected'.

doc/lispref/windows.texi

@@ -2028,8 +2028,8 @@ affected by a non-@code{nil} value of @code{window-combination-limit}.
 
 If you plan to use a sequence of @code{split-window} calls to produce a
 specific, predefined layout of windows on a frame, bind this variable
-temporarily to nil.  @code{window-state-put} (@pxref{Window
-Configurations}) and the functions to change window layouts
+temporarily to @code{nil}.  @code{window-state-put} (@pxref{Window
+Configurations}) and the functions which change window layouts
 (@pxref{Changing Window Layouts}) do that in order to restore a previous
 or systematically changed layout of a frame.
 @end defopt
@@ -2309,9 +2309,9 @@ below, we shall always assume that the windows displayed constitute
 their frame's main window and the @var{window} argument is @code{nil}
 unless stated otherwise.
 
+@cindex rotate window layout
    The first two commands rotate an entire window layout either
 clockwise or counterclockwise.
-@cindex rotate window layout
 
 @deffn Command window-layout-rotate-clockwise &optional window
 This command rotates the window layout clockwise by 90 degrees.  Imagine
@@ -2351,9 +2351,10 @@ layout in the opposite direction as demonstrated in the example below.
 @end smallexample
 @end deffn
 
-The next two commands @sc{flip} the window layout---rotate it around an
-imaginary horizontal or vertical axis.
 @cindex flip window layout
+The next two commands @sc{flip} the window layout---rotate it around an
+imaginary horizontal or vertical axis.  If the number of windows to be
+flipped is odd, the window in the middle remains in its original place.
 
 @deffn Command window-layout-flip-topdown &optional window
 This command flips windows such that windows on the bottom become
@@ -2413,17 +2414,17 @@ becomes a vertical split and vice versa.
 @end smallexample
 @end deffn
 
-The final two commands can be used to rotate windows within the existing
+@cindex rotating windows
+The final two commands can be used to @dfn{rotate} windows within the existing
 layout.  They are like the commands that rotate the layout but leave the
 underlying structure of the layout unchanged.  What actually changes are
 the positions of windows within the existing layout.  This happens in a
 way that the space formerly occupied by any window will be occupied by
-the window preceding (following if @var{reverse} is non-nil) it in the
-cyclic ordering of windows (@pxref{Cyclic Window Ordering}) on
+the window preceding (following if @var{reverse} is non-@code{nil}) it
+in the cyclic ordering of windows (@pxref{Cyclic Window Ordering}) on
 @var{window}'s frame.  These commands may signal an error if windows
 chosen to rotate are dedicated to their buffers, atomic or of fixed
 size.
-@cindex rotating windows
 
 @deffn Command rotate-windows &optional window reverse
 This command rotates @var{window}'c child windows in cyclic ordering.

etc/NEWS

@@ -358,14 +358,23 @@ increments as with Emacs 24 through Emacs 30 you now have to set
 
 +++
 *** New commands to modify window layouts of frames.
-'window-layout-rotate-clockwise' and its counterpart
-'window-layout-rotate-anticlockwise' rotate an entire window layout.
-'window-layout-flip-topdown' and 'window-layout-flip-leftright' flip the
-window layout vertically and horizontally.
-'window-layout-transpose' reorganizes windows such that every horizontal
-split becomes a vertical split and vice versa.
-'rotate-windows' and its counterpart 'rotate-windows-back' rotate
-windows in cylic ordering.
+'window-layout-rotate-clockwise' ('C-x w r <RIGHT>') and its counterpart
+'window-layout-rotate-anticlockwise' ('C-x v r <LEFT>') rotate an entire
+window layout.
+'window-layout-flip-topdown' ('C-x w r <DOWN>') and
+'window-layout-flip-leftright' ('C-x w r <LEFT>') flip the window layout
+vertically and horizontally.
+'window-layout-transpose' ('C-x w t') reorganizes windows such that
+every horizontal split becomes a vertical split and vice versa.
+'rotate-windows' ('C-x w o <RIGHT>') and its counterpart
+'rotate-windows-back' ('C-x w o <LEFT>') rotate windows in cyclic
+ordering.
+
+*** New user option 'rotate-windows-change-selected'.
+This controls whether 'rotate-windows' and 'rotate-windows-back' change
+the selected window.  If nil, the selected window does not change.
+The default is t, which means the new selected window will be the one
+that winds up at the location of the previously-selected window.
 
 +++
 *** Windmove commands now move to skipped windows if invoked twice in a row.

lisp/window-x.el

@@ -69,7 +69,7 @@ where HEIGHT and WIDTH are the normal height and width of the window.
 
 ;;;###autoload
 (defun window-layout-rotate-clockwise (&optional window)
-  "Clockwise rotate layout of WINDOW's child windows.
+  "Rotate layout of WINDOW's child windows clockwise by 90 degrees.
 WINDOW must be a parent window and defaults to the main window of the
 selected frame.  Interactively, with a prefix argument, rotate clockwise
 the layout of the child windows of the selected window's parent.  Signal
@@ -99,7 +99,7 @@ layout, consider using `rotate-windows-back' instead."
 
 ;;;###autoload
 (defun window-layout-flip-leftright (&optional window)
-  "Horizontally flip WINDOW's child windows.
+  "Flip WINDOW's child windows horizontally.
 WINDOW must be a parent window and defaults to the main window of the
 selected frame.  Interactively, with a prefix argument, flip
 horizontally the layout of the child windows of the selected window's
@@ -112,7 +112,7 @@ window on the right becomes a child window on the left and vice-versa."
 
 ;;;###autoload
 (defun window-layout-flip-topdown (&optional window)
-  "Vertically flip WINDOW's child windows.
+  "Flip WINDOW's child windows vertically.
 WINDOW must be a parent window and defaults to the main window of the
 selected frame.  Interactively, with a prefix argument, flip vertically
 the layout of the child windows of the selected window's parent.  Signal
@@ -143,6 +143,7 @@ a frame's selected window.  Otherwise, the new selected window will be
 the window that appears at the location of the previously selected
 window."
   :type 'boolean
+  :version "31.1"
   :group 'windows)
 
 ;;;###autoload