More updates to Window chapter of Lisp manual.

* doc/lispref/windows.texi (Splitting Windows): Clarify role of window
parameters in split-window.  Shorten the example.
(Deleting Windows): Rewrite intro to handle internal windows.  Fix
delete-windows-on doc.
(Selecting Windows): Copyedits.

2 files changed, 209 insertions, 277 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0fa50492481..232ddff6d3f 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2011-11-19  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Splitting Windows): Clarify role of window
+        parameters in split-window.  Shorten the example.
+        (Deleting Windows): Rewrite intro to handle internal windows.  Fix
+        delete-windows-on doc.
+        (Selecting Windows): Copyedits.
+
 2011-11-17  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Resizing Windows, Splitting Windows)
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 8c99a06909b..4e67fa6d740 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -110,6 +110,7 @@ including for the case where @var{object} is a deleted window.
 @end defun
 
 @cindex selected window
+@cindex window selected within a frame
   In each frame, at any time, exactly one Emacs window is designated
 as @dfn{selected within the frame}.  For the selected frame, that
 window is called the @dfn{selected window}---the one in which most
@@ -774,22 +775,24 @@ properties from it, including margins and scroll bars.  If
 @var{window} is an internal window, the new window inherits the
 properties of the window selected within @var{window}'s frame.
 
-If the variable @code{ignore-window-parameters} is non-@code{nil}
-(@pxref{Window Parameters}), this function ignores window parameters.
-Otherwise, it consults the @code{split-window} parameter of
-@var{window}; if this is @code{t}, it splits the window disregarding
-any other window parameters.  If the @code{split-window} parameter
-specifies a function, that function is called with the arguments
-@var{window}, @var{size}, and @var{side} to split @var{window}, in
-lieu of the usual action of @code{split-window}.
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+the @code{split-window} window parameter is @code{t}, this function
+ignores all other window parameters.  Otherwise, if the value of the
+@code{split-window} window parameter is a function, that function is
+called with the arguments @var{window}, @var{size}, and @var{side}, in
+lieu of the usual action of @code{split-window}.  Otherwise, this
+function obeys the @code{window-atom} or @code{window-side} window
+parameter, if any.  @xref{Window Parameters}.
 @end deffn
 
-  As an example, we show a combination of @code{split-window} calls
-that yields the window configuration discussed in @ref{Windows and
-Frames}.  This example demonstrates splitting a live window as well as
-splitting an internal window.  We begin with a frame containing a
-single window (a live root window), which we denote by @var{W4}.
-Calling @code{(split-window W3)} yields this window configuration:
+  As an example, here is a sequence of @code{split-window} calls that
+yields the window configuration discussed in @ref{Windows and Frames}.
+This example demonstrates splitting a live window as well as splitting
+an internal window.  We begin with a frame containing a single window
+(a live root window), which we denote by @var{W4}.  Calling
+@code{(split-window W3)} yields this window configuration:
 
 @smallexample
 @group
@@ -841,9 +844,6 @@ A new live window @var{W2} is created, to the left of the internal
 window @var{W3}.  A new internal window @var{W1} is created, becoming
 the new root window.
 
-  The following two options can be used to modify the operation of
-@code{split-window}.
-
 @defopt window-combination-resize
 If this variable is @code{nil}, @code{split-window} can only split a
 window (denoted by @var{window}) if @var{window}'s screen area is
@@ -854,18 +854,17 @@ If this variable is non-@code{nil}, @code{split-window} tries to
 resize all windows that are part of the same combination as
 @var{window}, in order to accommodate the new window.  In particular,
 this may allow @code{split-window} to succeed even if @var{window} is
-a fixed-size window or too small to ordinarily split.
-
-Also if this variable is non-@code{nil}, subsequent resizing and
-deleting @var{window} will usually affect @emph{all} windows in
-@var{window}'s combination.
+a fixed-size window or too small to ordinarily split.  Furthermore,
+subsequently resizing or deleting @var{window} may resize all other
+windows in its combination.
 
-The setting of this variable has no effect if
-@code{window-combination-limit} (see below) is non-@code{nil}.
+This variable has no effect if @code{window-combination-limit} is
+non-@code{nil} (see below).
 @end defopt
 
-To illustrate the use of @code{window-combination-resize} consider the
-following window configuration:
+  To illustrate the effect of @code{window-combination-resize},
+consider the following window configuration:
+
 @smallexample
 @group
      ______________________________________
@@ -886,9 +885,10 @@ following window configuration:
 @end group
 @end smallexample
 
-Splitting window @code{W3} with @code{window-combination-resize}
-@code{nil} produces a configuration where the size of @code{W2} remains
-unchanged:
+@noindent
+If @code{window-combination-resize} is @code{nil}, splitting window
+@code{W3} leaves the size of @code{W2} unchanged:
+
 @smallexample
 @group
      ______________________________________
@@ -909,8 +909,11 @@ unchanged:
 @end group
 @end smallexample
 
-Splitting @code{W3} with @code{window-combination-resize} non-@code{nil}
-instead steals the space for @code{W4} from both @code{W2} and @code{W3}:
+@noindent
+If @code{window-combination-resize} is non-@code{nil}, splitting
+@code{W3} instead leaves all three live windows with approximately the
+same height:
+
 @smallexample
 @group
      ______________________________________
@@ -932,53 +935,51 @@ instead steals the space for @code{W4} from both @code{W2} and @code{W3}:
 @end smallexample
 
 @defopt window-combination-limit
-If this variable is @code{nil}, @code{split-window} creates a new parent
-window if and only if the old window has no parent window or shall be
-split orthogonally to the combination it is part of.  If this variable
-is @code{t}, @code{split-window} always creates a new parent window.  If
-this variable is always @code{t}, a frame's window tree is a binary tree
-so every window but the frame's root window has exactly one sibling.
-Other values are reserved for future use.
-
-The value of this variable is also assigned to the combination-limit
-status of the new parent window.  The combination-limit status of any
-window can be retrieved via the function @code{window-combination-limit}
-and altered by the function @code{set-window-combination-limit}, see
-below.
+If the value of this variable is @code{t}, the @code{split-window}
+function always creates a new internal window.  If the value is
+@code{nil}, the new live window is allowed to share the existing
+parent window, if one exists, provided the split occurs in the same
+direction as the existing window combination (otherwise, a new
+internal window is created anyway).  The default is @code{nil}.  Other
+values are reserved for future use.
+
+Thus, if the value is always @code{t}, each window tree is a binary
+tree: each window except the root window has exactly one sibling.
+
+Furthermore, @code{split-window} calls
+@code{set-window-combination-limit} on the newly-created internal
+window, recording the current value of this variable.  This affects
+how the window tree is rearranged when the child windows are deleted
+(see below).
 @end defopt
 
-@defun window-combination-limit &optional window
-This function returns the combination-limit status of @var{window}.  The
-argument @var{window} can be any window and defaults to the selected
-one.  Note, however, that the combination-limit status is currently
-meaningful for internal windows only.
-
-@cindex combination-limit status
-The @dfn{combination-limit status} of a window specifies whether that
-window may be removed and its child windows recombined with that
-window's siblings when such a sibling's child window is deleted.  The
-combination-limit status is initially assigned by @code{split-window}
-from the current value of the variable @code{window-combination-limit}
-(see above) and can be reset by the function
-@code{set-window-combination-limit} (see below).
-
-If the return value is @code{nil}, child windows of @var{window} may be
-recombined with @var{window}'s siblings when a window gets deleted.  A
-return value of @code{nil} means that child windows of @var{window} are
-never (re-)combined with @var{window}'s siblings in such a case.
-@end defun
-
-@defun set-window-combination-limit window &optional status
-This functions sets the combination-limit status (see above) of
-@var{window} to @var{status}.  The argument @var{window} can be any
-window and defaults to the selected one.  Note that setting the
-combination-limit status is meaningful for internal windows only.  The
-return value is @var{status}.
-@end defun
-
-To illustrate the use of @code{window-combination-limit} consider the
-following configuration (throughout the following examples we shall
-assume that @code{window-combination-resize} invariantly is @code{nil}).
+@cindex window combination limit
+@defun set-window-combination-limit window status
+This functions sets the @dfn{combination limit} of the window
+@var{window} to @var{status}.  This value can be retrieved via the
+function @code{window-combination-limit}.  See below for its effects;
+note that it is only meaningful for internal windows.  The
+@code{split-window} function automatically calls this function,
+passing the value of the variable @code{window-combination-limit} as
+@var{status}.
+@end defun
+
+@defun window-combination-limit window
+This function returns the combination limit for @var{window}.
+
+The combination limit is meaningful only for an internal window.  If
+it is @code{nil}, then Emacs is allowed to automatically delete
+@var{window}, in response to a window deletion, in order to group the
+child windows of @var{window} with the child windows of one of its
+siblings to form a new window combination.  If the combination limit
+is @code{t}, the child windows of @var{window} are never automatically
+re-combined with its siblings'.
+@end defun
+
+  To illustrate the effect of @code{window-combination-limit},
+consider the following configuration (throughout this example, we will
+assume that @code{window-combination-resize} is @code{nil}):
+
 @smallexample
 @group
      ______________________________________
@@ -999,31 +1000,10 @@ assume that @code{window-combination-resize} invariantly is @code{nil}).
 @end group
 @end smallexample
 
-Splitting @code{W2} into two windows above each other with
-@code{window-combination-limit} equal @code{nil} will get you a
-configuration like:
-@smallexample
-@group
-     ______________________________________
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W4_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W3_________________||
-    |__________________W1__________________|
-
-@end group
-@end smallexample
+@noindent
+If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
+into two windows, one above the other, yields
 
-If you now enlarge window @code{W4}, Emacs steals the necessary space
-from window @code{W3} resulting in a configuration like:
 @smallexample
 @group
      ______________________________________
@@ -1034,43 +1014,24 @@ from window @code{W3} resulting in a configuration like:
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||                                    ||
     ||_________________W4_________________||
     | ____________________________________ |
     ||                                    ||
+    ||                                    ||
     ||_________________W3_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
-Deleting window @code{W4}, will return its space to @code{W2} as
-follows:
-@smallexample
-@group
-     ______________________________________
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||_________________W3_________________||
-    |__________________W1__________________|
+@noindent
+The newly-created window, @code{W4}, shares the same internal window
+@code{W1}.  If @code{W4} is resized, it is allowed to resize the other
+live window, @code{W3}.
 
-@end group
-@end smallexample
+  If @code{window-combination-limit} is @code{t}, splitting @code{W2}
+in the initial configuration would instead have produced this:
 
-Hence, with respect to the initial configuration, window @code{W2} has
-grown at the expense of window @code{W3}.  If, however, in the initial
-configuration you had split @code{W2} with
-@code{window-combination-limit} bound to @code{t}, a new internal window
-@code{W5} would have been created as depicted below.
 @smallexample
 @group
      ______________________________________
@@ -1091,143 +1052,110 @@ configuration you had split @code{W2} with
 @end group
 @end smallexample
 
-Enlarging @code{W4} would now have stolen the necessary space from
-@code{W2} instead of @code{W3} as
-@smallexample
-@group
-     ______________________________________
-    | ____________________________________ |
-    || __________________________________ ||
-    |||________________W2________________|||
-    || __________________________________ ||
-    |||                                  |||
-    |||                                  |||
-    |||________________W4________________|||
-    ||_________________W5_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W3_________________||
-    |__________________W1__________________|
-
-@end group
-@end smallexample
+@noindent
+A new internal window @code{W5} has been created; its children are
+@code{W2} and the new live window @code{W4}.  Now, @code{W2} is the
+only sibling of @code{W4}, so resizing @code{W4} will resize
+@code{W2}, leaving @code{W3} unaffected.
 
-and the subsequent deletion of @code{W4} would have restored the initial
-configuration.
+  For interactive use, Emacs provides two commands which always split
+the selected window.  These call @code{split-window} internally.
 
-For interactive use, Emacs provides two commands which always split the
-selected window.
+@deffn Command split-window-right &optional size
+This function splits the selected window into two side-by-side
+windows, putting the selected window on the left.  If @var{size} is
+positive, the left window gets @var{size} columns; if @var{size} is
+negative, the right window gets @minus{}@var{size} columns.
+@end deffn
 
 @deffn Command split-window-below &optional size
-This function splits the selected window into two windows, one above the
-other, leaving the upper of the two windows selected, with @var{size}
-lines.  (If @var{size} is negative, then the lower of the two windows
-gets @minus{}@var{size} lines and the upper window gets the rest, but
-the upper window is still the one selected.)  However, if
-@code{split-window-keep-point} (see below) is @code{nil}, then either
-window can be selected.
-
-   In other respects, this function is similar to @code{split-window}.
-In particular, the upper window is the original one and the return value
-is the new, lower window.
+This function splits the selected window into two windows, one above
+the other, leaving the upper window selected.  If @var{size} is
+positive, the upper window gets @var{size} lines; if @var{size} is
+negative, the lower window gets @minus{}@var{size} lines.
 @end deffn
 
 @defopt split-window-keep-point
-If this variable is non-@code{nil} (the default), then
+If the value of this variable is non-@code{nil} (the default),
 @code{split-window-below} behaves as described above.
 
-   If it is @code{nil}, then @code{split-window-below} adjusts point
-in each of the two windows to avoid scrolling.  (This is useful on
-slow terminals.)  It selects whichever window contains the screen line
-that point was previously on.  Other functions are not affected by
-this variable.
+If it is @code{nil}, @code{split-window-below} adjusts point in each
+of the two windows to minimize redisplay.  (This is useful on slow
+terminals.)  It selects whichever window contains the screen line that
+point was previously on.  Note that this only affects
+@code{split-window-below}, not the lower-level @code{split-window}
+function.
 @end defopt
 
-@deffn Command split-window-right &optional size
-This function splits the selected window into two windows
-side-by-side, leaving the selected window on the left with @var{size}
-columns.  If @var{size} is negative, the rightmost window gets
-@minus{}@var{size} columns, but the leftmost window still remains
-selected.
-@end deffn
-
-
 @node Deleting Windows
 @section Deleting Windows
 @cindex deleting windows
 
-A window remains visible on its frame unless you @dfn{delete} it by
-calling certain functions that delete windows.  A deleted window cannot
-appear on the screen, but continues to exist as a Lisp object until
-there are no references to it.  There is no way to cancel the deletion
-of a window aside from restoring a saved window configuration
-(@pxref{Window Configurations}).  Restoring a window configuration also
-deletes any windows that aren't part of that configuration.  Erroneous
-information may result from using a deleted window as if it were live.
+  @dfn{Deleting} a window removes it from the frame's window tree.  If
+the window is a live window, it disappears from the screen.  If the
+window is an internal window, its child windows are deleted too.
+
+  Even after a window is deleted, it continues to exist as a Lisp
+object, until there are no more references to it.  Window deletion can
+be reversed, by restoring a saved window configuration (@pxref{Window
+Configurations}).
 
 @deffn Command delete-window &optional window
-This function removes @var{window} from display and returns @code{nil}.
-The argument @var{window} can denote any window and defaults to the
-selected one.  An error is signaled if @var{window} is the only window
-on its frame.  Hence @var{window} must have at least one sibling window
-(@pxref{Windows and Frames}) in order to get deleted.  If @var{window}
-is the selected window on its frame, this function selects the most
-recently selected live window on that frame instead.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}.  Otherwise, if the @code{delete-window} parameter of
-@var{window} is @code{t}, it deletes the window disregarding other
-window parameters.  If the @code{delete-window} parameter specifies a
-function, that function is called with @var{window} as its sole
-argument.
-
-If @code{window-combination-resize} (@pxref{Splitting Windows}) is
-@code{nil}, the space @var{window} took up is given to its left sibling
-if such a window exists and to its right sibling otherwise.  If
-@code{window-combination-resize} is non-@code{nil}, the space of
-@var{window} is proportionally distributed among the remaining windows
-in the same combination.
+This function removes @var{window} from display and returns
+@code{nil}.  If @var{window} is omitted or @code{nil}, it defaults to
+the selected window.  If deleting the window would leave no more
+windows in the window tree (e.g. if it is the only live window in the
+frame), an error is signaled.
+
+By default, the space taken up by @var{window} is given to one of its
+adjacent sibling windows, if any.  However, if the variable
+@code{window-combination-resize} is non-@code{nil}, the space is
+proportionally distributed among any remaining windows in the window
+combination.  @xref{Splitting Windows}.
+
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+the @code{delete-window} window parameter is @code{t}, this function
+ignores all other window parameters.  Otherwise, if the value of the
+@code{delete-window} window parameter is a function, that function is
+called with the argument @var{window}, in lieu of the usual action of
+@code{delete-window}.  Otherwise, this function obeys the
+@code{window-atom} or @code{window-side} window parameter, if any.
+@xref{Window Parameters}.
 @end deffn
 
 @deffn Command delete-other-windows &optional window
-This function makes @var{window} fill its frame and returns @code{nil}.
-The argument @var{window} can denote an arbitrary window and defaults to
-the selected one.  Upon exit, @var{window} will be the selected window
-on its frame.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}.  Otherwise, if the @code{delete-other-windows} parameter
-of @var{window} equals @code{t}, it deletes all other windows
-disregarding any remaining window parameters.  If the
-@code{delete-other-windows} parameter of @var{window} specifies a
-function, it calls that function with @var{window} as its sole argument.
+This function makes @var{window} fill its frame, by deleting other
+windows as necessary.  If @var{window} is omitted or @code{nil}, it
+defaults to the selected window.  The return value is @code{nil}.
+
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+the @code{delete-other-windows} window parameter is @code{t}, this
+function ignores all other window parameters.  Otherwise, if the value
+of the @code{delete-other-windows} window parameter is a function,
+that function is called with the argument @var{window}, in lieu of the
+usual action of @code{delete-other-windows}.  Otherwise, this function
+obeys the @code{window-atom} or @code{window-side} window parameter,
+if any.  @xref{Window Parameters}.
 @end deffn
 
 @deffn Command delete-windows-on &optional buffer-or-name frame
-This function deletes all windows showing @var{buffer-or-name}.  If
-there are no windows showing @var{buffer-or-name}, it does nothing.
-The optional argument @var{buffer-or-name} may be a buffer or the name
-of an existing buffer and defaults to the current buffer.  Invoking
-this command on a minibuffer signals an error.
-
-The function @code{delete-windows-on} operates by calling
-@code{delete-window} for each window showing @var{buffer-or-name}.  If a
-frame has several windows showing different buffers, then those showing
-@var{buffer-or-name} are removed, and the other windows expand to fill
-the space.
-
-If all windows in some frame are showing @var{buffer-or-name} (including
-the case where there is only one window), then that frame is deleted
-provided there are other frames left.
-
-The optional argument @var{frame} specifies which frames to operate on.
-This function does not use it in quite the same way as the other
-functions which scan all live windows (@pxref{Cyclic Window Ordering});
-specifically, the values @code{t} and @code{nil} have the opposite of
-their meanings in the other functions.  Here are the full details:
+This function deletes all windows showing @var{buffer-or-name}, by
+calling @code{delete-window} on those windows.  @var{buffer-or-name}
+should be a buffer, or the name of a buffer; if omitted or @code{nil},
+it defaults to the current buffer.  If there are no windows showing
+the specified buffer, this function does nothing.  If the specified
+buffer is a minibuffer, an error is signaled.
+
+If there is a dedicated window showing the buffer, and that window is
+the only one on its frame, this function also deletes that frame if it
+is not the only frame on the terminal.
+
+The optional argument @var{frame} specifies which frames to operate
+on:
 
 @itemize @bullet
 @item @code{nil}
@@ -1241,34 +1169,37 @@ means operate on all visible or iconified frames.
 @item A frame
 means operate on that frame.
 @end itemize
-@end deffn
 
+Note that this argument does not have the same meaning as in other
+functions which scan all live windows (@pxref{Cyclic Window
+Ordering}).  Specifically, the values @code{t} and @code{nil} have the
+opposite of their meanings in those other functions.
+@end deffn
 
 @node Selecting Windows
 @section Selecting Windows
 @cindex selecting a window
 
 @defun select-window window &optional norecord
-This function makes @var{window} the selected window, see @ref{Basic
-Windows}.  Unless @var{window} already is the selected window, this also
-makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
-buffer.  Moreover, the cursor for selected windows will be displayed in
-@var{window} after the next redisplay.  This function returns
-@var{window}.
+This function makes @var{window} the selected window, as well as the
+window selected within its frame (@pxref{Basic Windows}).
+@var{window} must be a live winow.  Unless @var{window} already is the
+selected window, its buffer becomes the current buffer (@pxref{Buffers
+and Windows}).  The return value is @var{window}.
 
-Normally, @var{window}'s selected buffer is moved to the front of the
-buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
-recently selected window.  But if the optional argument @var{norecord}
-is non-@code{nil}, the buffer list remains unchanged and @var{window}
-does not become the most recently selected one.
+By default, this function also moves @var{window}'s selected buffer to
+the front of the buffer list (@pxref{The Buffer List}), and makes
+@var{window} the most recently selected window.  However, if the
+optional argument @var{norecord} is non-@code{nil}, these additional
+actions are omitted.
 @end defun
 
 @cindex most recently selected windows
-The sequence of calls to @code{select-window} with a non-@code{nil}
+  The sequence of calls to @code{select-window} with a non-@code{nil}
 @var{norecord} argument determines an ordering of windows by their
 selection time.  The function @code{get-lru-window} can be used to
-retrieve the least recently selected live window in this ordering, see
-@ref{Cyclic Window Ordering}.
+retrieve the least recently selected live window (@pxref{Cyclic Window
+Ordering}).
 
 @defmac save-selected-window forms@dots{}
 This macro records the selected frame, as well as the selected window
@@ -1300,33 +1231,26 @@ The order of recently selected windows and the buffer list are not
 changed by this macro.
 @end defmac
 
-@cindex frame selected window
-@cindex window selected within frame
-Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
-one window on any frame is selected within the frame.  The significance
-of this designation is that selecting the frame also selects this
-window.  Conversely, selecting a window for Emacs with
-@code{select-window} also makes that window selected within its frame.
-
-@defun frame-selected-window  &optional frame
-This function returns the window on @var{frame} that is selected within
-@var{frame}.  The optional argument @var{frame} must denote a live frame
-and defaults to the selected one.
+@defun frame-selected-window &optional frame
+This function returns the window on @var{frame} that is selected
+within that frame.  @var{frame} should be a live frame; if omitted or
+@code{nil}, it defaults to the selected frame.
 @end defun
 
 @defun set-frame-selected-window frame window &optional norecord
-This function sets the selected window of frame @var{frame} to
-@var{window}.  The argument @var{frame} must denote a live frame and
-defaults to the selected one.  If @var{frame} is the selected frame,
-this also makes @var{window} the selected window.  The argument
-@var{window} must denote a live window.  This function returns
-@var{window}.
+This function makes @code{window} the window selected within the frame
+@var{frame}.  @var{frame} should be a live frame; if omitted or
+@code{nil}, it defaults to the selected frame.  @var{window} should be
+a live window; if omitted or @code{nil}, it defaults to the selected
+window.
 
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the list of most recently selected windows (@pxref{Selecting Windows})
-nor the buffer list (@pxref{The Buffer List}).
-@end defun
+If @var{frame} is the selected frame, this makes @var{window} the
+selected window.
 
+If the optional argument @var{norecord} is non-@code{nil}, this
+function does not alter the list of most recently selected windows,
+nor the buffer list.
+@end defun
 
 @node Cyclic Window Ordering
 @section Cyclic Ordering of Windows