[Emacs-diffs] /srv/bzr/emacs/trunk r109852: Recommand against save-window-excursion in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 109852
fixes bug: http://debbugs.gnu.org/12075
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-09-02 12:47:28 +0800
message:
  Recommand against save-window-excursion in Lisp manual.
  
  * windows.texi (Window Configurations): Recommend against using
  save-window-excursion.
  
  * control.texi (Catch and Throw):
  * positions.texi (Excursions): Don't mention it.
modified:
  doc/lispref/ChangeLog
  doc/lispref/control.texi
  doc/lispref/positions.texi
  doc/lispref/windows.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-01 01:04:26 +0000
+++ b/doc/lispref/ChangeLog     2012-09-02 04:47:28 +0000
@@ -1,3 +1,11 @@
+2012-09-02  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        Better seed support for (random).

=== modified file 'doc/lispref/control.texi'
--- a/doc/lispref/control.texi  2012-05-27 01:34:14 +0000
+++ b/doc/lispref/control.texi  2012-09-02 04:47:28 +0000
@@ -556,16 +556,14 @@
 @code{catch} in between).
 
   Executing @code{throw} exits all Lisp constructs up to the matching
address@hidden, including function calls.  When binding constructs such as
address@hidden or function calls are exited in this way, the bindings are
-unbound, just as they are when these constructs exit normally
address@hidden, 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
address@hidden 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

=== modified file 'doc/lispref/positions.texi'
--- a/doc/lispref/positions.texi        2012-06-17 05:13:40 +0000
+++ b/doc/lispref/positions.texi        2012-09-02 04:47:28 +0000
@@ -850,9 +850,6 @@
 @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

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2012-08-21 09:50:58 +0000
+++ b/doc/lispref/windows.texi  2012-09-02 04:47:28 +0000
@@ -3153,42 +3153,21 @@
 @end defun
 
 @defmac save-window-excursion address@hidden
-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
address@hidden  (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:
-
address@hidden
address@hidden
-(split-window)
-     @result{} #<window 25 on control.texi>
address@hidden group
address@hidden
-(setq w (selected-window))
-     @result{} #<window 19 on control.texi>
address@hidden group
address@hidden
-(save-window-excursion
-  (delete-other-windows w)
-  (switch-to-buffer "foo")
-  'do-something)
-     @result{} do-something
-     ;; @r{The screen is now split again.}
address@hidden group
address@hidden 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
address@hidden
+
+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
address@hidden 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
@@ -3424,11 +3403,11 @@
 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
address@hidden (@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