Commit 6a787d9a authored by Chong Yidong's avatar Chong Yidong
Browse files

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.

Fixes: debbugs:12075
parent 48c948de
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> 2012-09-01 Paul Eggert <eggert@cs.ucla.edu>
Better seed support for (random). Better seed support for (random).
......
...@@ -556,16 +556,14 @@ the @code{catch} in @code{foo-outer} specifies the same symbol, so that ...@@ -556,16 +556,14 @@ the @code{catch} in @code{foo-outer} specifies the same symbol, so that
@code{catch} in between). @code{catch} in between).
Executing @code{throw} exits all Lisp constructs up to the matching Executing @code{throw} exits all Lisp constructs up to the matching
@code{catch}, including function calls. When binding constructs such as @code{catch}, including function calls. When binding constructs such
@code{let} or function calls are exited in this way, the bindings are as @code{let} or function calls are exited in this way, the bindings
unbound, just as they are when these constructs exit normally are unbound, just as they are when these constructs exit normally
(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer (@pxref{Local Variables}). Likewise, @code{throw} restores the buffer
and position saved by @code{save-excursion} (@pxref{Excursions}), and and position saved by @code{save-excursion} (@pxref{Excursions}), and
the narrowing status saved by @code{save-restriction} and the window the narrowing status saved by @code{save-restriction}. It also runs
selection saved by @code{save-window-excursion} (@pxref{Window any cleanups established with the @code{unwind-protect} special form
Configurations}). It also runs any cleanups established with the when it exits that form (@pxref{Cleanups}).
@code{unwind-protect} special form when it exits that form
(@pxref{Cleanups}).
The @code{throw} need not appear lexically within the @code{catch} The @code{throw} need not appear lexically within the @code{catch}
that it jumps to. It can equally well be called from another function that it jumps to. It can equally well be called from another function
......
...@@ -850,9 +850,6 @@ after setting the desired current buffer, as in the following example: ...@@ -850,9 +850,6 @@ after setting the desired current buffer, as in the following example:
@cindex window excursions @cindex window excursions
Likewise, @code{save-excursion} does not restore window-buffer Likewise, @code{save-excursion} does not restore window-buffer
correspondences altered by functions such as @code{switch-to-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 @strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all point value relocates the saved value, just as it relocates all
......
...@@ -3153,42 +3153,21 @@ as @code{save-window-excursion}: ...@@ -3153,42 +3153,21 @@ as @code{save-window-excursion}:
@end defun @end defun
@defmac save-window-excursion forms@dots{} @defmac save-window-excursion forms@dots{}
This special form records the window configuration, executes @var{forms} This macro records the window configuration of the selected frame,
in sequence, then restores the earlier window configuration. The window executes @var{forms} in sequence, then restores the earlier window
configuration includes, for each window, the value of point and the configuration. The return value is the value of the final form in
portion of the buffer that is visible. It also includes the choice of @var{forms}.
selected window. However, it does not include the value of point in
the current buffer; use @code{save-excursion} also, if you wish to Most Lisp code should not use this macro; @code{save-selected-window}
preserve that. is typically sufficient. In particular, this macro cannot reliably
prevent the code in @var{forms} from opening new windows, because new
Don't use this construct when @code{save-selected-window} is sufficient. windows might be opened in other frames (@pxref{Choosing Window}), and
@code{save-window-excursion} only saves and restores the window
Exit from @code{save-window-excursion} always triggers execution of configuration on the current frame.
@code{window-size-change-functions}. (It doesn't know how to tell
whether the restored configuration actually differs from the one in Do not use this macro in @code{window-size-change-functions}; exiting
effect at the end of the @var{forms}.) the macro triggers execution of @code{window-size-change-functions},
leading to an endless loop.
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
@end defmac @end defmac
@defun window-configuration-p object @defun window-configuration-p object
...@@ -3424,11 +3403,11 @@ Creating or deleting windows counts as a size change, and therefore ...@@ -3424,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 causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows. counts, because it changes the sizes of the existing windows.
It is not a good idea to use @code{save-window-excursion} (@pxref{Window You may use @code{save-selected-window} in these functions
Configurations}) in these functions, because that always counts as a (@pxref{Selecting Windows}). However, do not use
size change, and it would cause these functions to be called over and @code{save-window-excursion} (@pxref{Window Configurations}); exiting
over. In most cases, @code{save-selected-window} (@pxref{Selecting that macro counts as a size change, which would cause these functions
Windows}) is what you need here. to be called over and over.
@end defvar @end defvar
@defvar window-configuration-change-hook @defvar window-configuration-change-hook
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment