5 files changed, 77 insertions, 83 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 6579cc48fd5..b0156e5ac7e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,23 @@
+2012-09-02  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Window Configurations): Recommend against using
+        save-window-excursion (Bug#12075).
+
+        * control.texi (Catch and Throw):
+        * positions.texi (Excursions): Don't mention it.
+
+2012-09-01  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Better seed support for (random).
+        * numbers.texi (Random Numbers): Document new behavior of
+        the calls (random) and (random STRING).
+
+2012-08-21  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Window Point): Document recent changes in
+        window-point and set-window-point.
+        (Selecting Windows): Document recent change in select-window.
+
 2012-08-06  Eli Zaretskii  <eliz@gnu.org>
 
         * functions.texi (Closures): Put the main index entry for
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 07d2d0d993c..25a7655b7b8 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -556,16 +556,14 @@ the @code{catch} in @code{foo-outer} specifies the same symbol, so that
 @code{catch} in between).
 
   Executing @code{throw} exits all Lisp constructs up to the matching
-@code{catch}, including function calls.  When binding constructs such as
-@code{let} or function calls are exited in this way, the bindings are
-unbound, just as they are when these constructs exit normally
+@code{catch}, including function calls.  When binding constructs such
+as @code{let} or function calls are exited in this way, the bindings
+are unbound, just as they are when these constructs exit normally
 (@pxref{Local Variables}).  Likewise, @code{throw} restores the buffer
 and position saved by @code{save-excursion} (@pxref{Excursions}), and
-the narrowing status saved by @code{save-restriction} and the window
-selection saved by @code{save-window-excursion} (@pxref{Window
-Configurations}).  It also runs any cleanups established with the
-@code{unwind-protect} special form when it exits that form
-(@pxref{Cleanups}).
+the narrowing status saved by @code{save-restriction}.  It also runs
+any cleanups established with the @code{unwind-protect} special form
+when it exits that form (@pxref{Cleanups}).
 
   The @code{throw} need not appear lexically within the @code{catch}
 that it jumps to.  It can equally well be called from another function
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index ce0716f39ef..17f3ee099bd 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -1199,30 +1199,32 @@ numbers are not truly random, but they have certain properties that
 mimic a random series.  For example, all possible values occur equally
 often in a pseudo-random series.
 
-In Emacs, pseudo-random numbers are generated from a ``seed'' number.
+In Emacs, pseudo-random numbers are generated from a ``seed''.
 Starting from any given seed, the @code{random} function always
-generates the same sequence of numbers.  Emacs always starts with the
-same seed value, so the sequence of values of @code{random} is actually
-the same in each Emacs run!  For example, in one operating system, the
-first call to @code{(random)} after you start Emacs always returns
-@minus{}1457731, and the second one always returns @minus{}7692030.  This
-repeatability is helpful for debugging.
-
-If you want random numbers that don't always come out the same, execute
-@code{(random t)}.  This chooses a new seed based on the current time of
-day and on Emacs's process @acronym{ID} number.
+generates the same sequence of numbers.  Emacs typically starts with a
+different seed each time, so the sequence of values of @code{random}
+typically differs in each Emacs run.
+
+Sometimes you want the random number sequence to be repeatable.  For
+example, when debugging a program whose behavior depends on the random
+number sequence, it is helpful to get the same behavior in each
+program run.  To make the sequence repeat, execute @code{(random "")}.
+This sets the seed to a constant value for your particular Emacs
+executable (though it may differ for other Emacs builds).  You can use
+other strings to choose various seed values.
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a
 series of pseudo-random integers.
 
 If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit}.
+nonnegative and less than @var{limit}.  Otherwise, the value
+might be any integer representable in Lisp.
 
 If @var{limit} is @code{t}, it means to choose a new seed based on the
 current time of day and on Emacs's process @acronym{ID} number.
 
-On some machines, any integer representable in Lisp may be the result
-of @code{random}.  On other machines, the result can never be larger
-than a certain maximum or less than a certain (negative) minimum.
+If @var{limit} is a string, it means to choose a new seed based on the
+string's contents.
+
 @end defun
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index a59a99d124c..a0c65319850 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -850,9 +850,6 @@ after setting the desired current buffer, as in the following example:
 @cindex window excursions
   Likewise, @code{save-excursion} does not restore window-buffer
 correspondences altered by functions such as @code{switch-to-buffer}.
-One way to restore these correspondences, and the selected window, is to
-use @code{save-window-excursion} inside @code{save-excursion}
-(@pxref{Window Configurations}).
 
   @strong{Warning:} Ordinary insertion of text adjacent to the saved
 point value relocates the saved value, just as it relocates all
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index c7c466c7d36..5fe007ba02d 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1129,16 +1129,15 @@ are the opposite of what they are in those other functions.
 
 @defun select-window window &optional norecord
 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 window.  Unless @var{window} already is the
-selected window, its buffer becomes the current buffer (@pxref{Buffers
-and Windows}).  The return value is @var{window}.
+window selected within its frame (@pxref{Basic Windows}).  @var{window}
+must be a live window.  This function makes also @var{window}'s buffer
+current (@pxref{Buffers and Windows}).  The return value is
+@var{window}.
 
-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.
+By default, this function also moves @var{window}'s 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
@@ -2276,19 +2275,18 @@ For a nonselected window, this is the value point would have (in that
 window's buffer) if that window were selected.  The default for
 @var{window} is the selected window.
 
-When @var{window} is the selected window and its buffer is also the
-current buffer, the value returned is the same as point in that buffer.
-Strictly speaking, it would be more correct to return the ``top-level''
-value of point, outside of any @code{save-excursion} forms.  But that
-value is hard to find.
+When @var{window} is the selected window, the value returned is the
+value of point in that window's buffer.  Strictly speaking, it would be
+more correct to return the ``top-level'' value of point, outside of any
+@code{save-excursion} forms.  But that value is hard to find.
 @end defun
 
 @defun set-window-point window position
 This function positions point in @var{window} at position
 @var{position} in @var{window}'s buffer.  It returns @var{position}.
 
-If @var{window} is selected, and its buffer is current,
-this simply does @code{goto-char}.
+If @var{window} is selected, this simply does @code{goto-char} in
+@var{window}'s buffer.
 @end defun
 
 @defvar window-point-insertion-type
@@ -3155,42 +3153,21 @@ as @code{save-window-excursion}:
 @end defun
 
 @defmac save-window-excursion forms@dots{}
-This special form records the window configuration, executes @var{forms}
-in sequence, then restores the earlier window configuration.  The window
-configuration includes, for each window, the value of point and the
-portion of the buffer that is visible.  It also includes the choice of
-selected window.  However, it does not include the value of point in
-the current buffer; use @code{save-excursion} also, if you wish to
-preserve that.
-
-Don't use this construct when @code{save-selected-window} is sufficient.
-
-Exit from @code{save-window-excursion} always triggers execution of
-@code{window-size-change-functions}.  (It doesn't know how to tell
-whether the restored configuration actually differs from the one in
-effect at the end of the @var{forms}.)
-
-The return value is the value of the final form in @var{forms}.
-For example:
-
-@example
-@group
-(split-window)
-     @result{} #<window 25 on control.texi>
-@end group
-@group
-(setq w (selected-window))
-     @result{} #<window 19 on control.texi>
-@end group
-@group
-(save-window-excursion
-  (delete-other-windows w)
-  (switch-to-buffer "foo")
-  'do-something)
-     @result{} do-something
-     ;; @r{The screen is now split again.}
-@end group
-@end example
+This macro records the window configuration of the selected frame,
+executes @var{forms} in sequence, then restores the earlier window
+configuration.  The return value is the value of the final form in
+@var{forms}.
+
+Most Lisp code should not use this macro; @code{save-selected-window}
+is typically sufficient.  In particular, this macro cannot reliably
+prevent the code in @var{forms} from opening new windows, because new
+windows might be opened in other frames (@pxref{Choosing Window}), and
+@code{save-window-excursion} only saves and restores the window
+configuration on the current frame.
+
+Do not use this macro in @code{window-size-change-functions}; exiting
+the macro triggers execution of @code{window-size-change-functions},
+leading to an endless loop.
 @end defmac
 
 @defun window-configuration-p object
@@ -3426,11 +3403,11 @@ Creating or deleting windows counts as a size change, and therefore
 causes these functions to be called.  Changing the frame size also
 counts, because it changes the sizes of the existing windows.
 
-It is not a good idea to use @code{save-window-excursion} (@pxref{Window
-Configurations}) in these functions, because that always counts as a
-size change, and it would cause these functions to be called over and
-over.  In most cases, @code{save-selected-window} (@pxref{Selecting
-Windows}) is what you need here.
+You may use @code{save-selected-window} in these functions
+(@pxref{Selecting Windows}).  However, do not use
+@code{save-window-excursion} (@pxref{Window Configurations}); exiting
+that macro counts as a size change, which would cause these functions
+to be called over and over.
 @end defvar
 
 @defvar window-configuration-change-hook