changeset 106731:79fa2d910b72

Avoid dubious uses of save-excursions. * doc/lispref/positions.texi (Excursions): Recommend the use of save-current-buffer if applicable. * doc/lispref/text.texi (Clickable Text): Fix the example code which used save-excursion in a naive way which sometimes preserves point and sometimes not. * doc/lispref/variables.texi (Creating Buffer-Local): * doc/lispref/os.texi (Session Management): * doc/lispref/display.texi (GIF Images): * doc/lispref/control.texi (Cleanups): Use (save|with)-current-buffer. * doc/misc/gnus.texi (Posting Styles): Use with-current-buffer. * doc/misc/calc.texi (Defining Simple Commands): Prefer save-current-buffer.

--- a/doc/lispref/ChangeLog	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/ChangeLog	Mon Jan 04 13:18:38 2010 -0500
@@ -1,3 +1,16 @@
[phone]  Stefan Monnier  <[e-mail]>
+
+	Avoid dubious uses of save-excursions.
+	* positions.texi (Excursions): Recommend the use of
+	save-current-buffer if applicable.
+	* text.texi (Clickable Text): Fix the example code which used
+	save-excursion in a naive way which sometimes preserves point and
+	sometimes not.
+	* variables.texi (Creating Buffer-Local):
+	* os.texi (Session Management):
+	* display.texi (GIF Images):
+	* control.texi (Cleanups): Use (save|with)-current-buffer.
+
 2010-01-02  Eli Zaretskii  <[e-mail]>
 
 	* modes.texi (Example Major Modes): Fix indentation.  (Bug#5195)
@@ -8375,7 +8388,7 @@
 ;; End:
 
     Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-      2007, 2008, 2009  Free Software Foundation, Inc.
+      2007, 2008, 2009, 2010  Free Software Foundation, Inc.
 
   This file is part of GNU Emacs.
 

--- a/doc/lispref/control.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/control.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -1255,9 +1255,8 @@
 
 @smallexample
 @group
-(save-excursion
-  (let ((buffer (get-buffer-create " *temp*")))
-    (set-buffer buffer)
+(let ((buffer (get-buffer-create " *temp*")))
+  (with-current-buffer buffer
     (unwind-protect
         @var{body-form}
       (kill-buffer buffer))))
@@ -1269,7 +1268,7 @@
 (current-buffer))} and dispense with the variable @code{buffer}.
 However, the way shown above is safer, if @var{body-form} happens to
 get an error after switching to a different buffer!  (Alternatively,
-you could write another @code{save-excursion} around @var{body-form},
+you could write a @code{save-current-buffer} around @var{body-form},
 to ensure that the temporary buffer becomes current again in time to
 kill it.)
 

--- a/doc/lispref/display.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/display.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -4394,8 +4394,7 @@
   (when (= idx max)
     (setq idx 0))
   (let ((img (create-image file nil :image idx)))
-    (save-excursion
-      (set-buffer buffer)
+    (with-current-buffer buffer
       (goto-char (point-min))
       (unless first-time (delete-char 1))
       (insert-image img))

--- a/doc/lispref/os.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/os.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -2182,7 +2182,7 @@
 
 @group
 (defun save-yourself-test ()
-  (insert "(save-excursion
+  (insert "(save-current-buffer
   (switch-to-buffer \"*scratch*\")
   (insert \"I am restored\"))")
   nil)

--- a/doc/lispref/positions.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/positions.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -806,7 +806,9 @@
 
   The forms for saving and restoring the configuration of windows are
 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
-Configurations}).
+Configurations}).  When only the identity of the current buffer needs
+to be saved and restored, it is preferable to use
+@code{save-current-buffer} instead.
 
 @defspec save-excursion body@dots{}
 @cindex mark excursion
@@ -817,10 +819,10 @@
 point and the mark.  All three saved values are restored even in case of
 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 
-The @code{save-excursion} special form is the standard way to switch
-buffers or move point within one part of a program and avoid affecting
-the rest of the program.  It is used more than 4000 times in the Lisp
-sources of Emacs.
+The @code{save-excursion} special form is the standard way to move
+point within one part of a program and avoid affecting the rest of the
+program.  It is used more than 4000 times in the Lisp sources
+of Emacs.
 
 @code{save-excursion} does not save the values of point and the mark for
 other buffers, so changes in other buffers remain in effect after

--- a/doc/lispref/text.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/text.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -3524,13 +3524,12 @@
 (defun dired-mouse-find-file-other-window (event)
   "In Dired, visit the file or directory name you click on."
   (interactive "e")
-  (let (window pos file)
-    (save-excursion
-      (setq window (posn-window (event-end event))
-            pos (posn-point (event-end event)))
-      (if (not (windowp window))
-          (error "No file chosen"))
-      (set-buffer (window-buffer window))
+  (let ((window (posn-window (event-end event)))
+        (pos (posn-point (event-end event)))
+        file)
+    (if (not (windowp window))
+        (error "No file chosen"))
+    (with-current-buffer (window-buffer window)
       (goto-char pos)
       (setq file (dired-get-file-for-visit)))
     (if (file-directory-p file)

--- a/doc/lispref/variables.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/lispref/variables.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -1240,8 +1240,7 @@
 
 @group
 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
-(save-excursion
-  (set-buffer "b2")
+(with-current-buffer "b2"
   foo)
      @result{} 5
 @end group

--- a/doc/misc/ChangeLog	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/misc/ChangeLog	Mon Jan 04 13:18:38 2010 -0500
@@ -1,3 +1,8 @@
[phone]  Stefan Monnier  <[e-mail]>
+
+	* gnus.texi (Posting Styles): Use with-current-buffer.
+	* calc.texi (Defining Simple Commands): Prefer save-current-buffer.
+
 2010-01-02  Kevin Ryde  <[e-mail]>
 
 	* eieio.texi (Naming Conventions): Correction to xref on elisp
@@ -6512,7 +6517,7 @@
 ;; End:
 
     Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
-      2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
+      2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
 
   This file is part of GNU Emacs.
 

--- a/doc/misc/calc.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/misc/calc.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -31968,7 +31968,7 @@
 @smallexample
 (let ((calc-command-flags nil))
   (unwind-protect
-      (save-excursion
+      (save-current-buffer
         (calc-select-buffer)
         @emph{body of function}
         @emph{renumber stack}

--- a/doc/misc/gnus.texi	Mon Jan 04 12:38:20 2010 -0500
+++ b/doc/misc/gnus.texi	Mon Jan 04 13:18:38 2010 -0500
@@ -10,7 +10,7 @@
 
 @copying
 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -13449,8 +13449,7 @@
          (body "You are fired.\n\nSincerely, your boss.")
          (organization "Important Work, Inc"))
         ("nnml:.*"
-         (From (save-excursion
-                 (set-buffer gnus-article-buffer)
+         (From (with-current-buffer gnus-article-buffer
                  (message-fetch-field "to"))))
         ("^nn.+:"
          (signature-file "~/.mail-signature"))))