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.

7 files changed, 33 insertions, 22 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e7467c20d25..6dfc203f638 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,16 @@
+2010-01-04  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        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  <eliz@gnu.org>
 
         * 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.
 
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 41f844b4e21..6d7c01d354b 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1255,9 +1255,8 @@ make sure to kill it before finishing:
 
 @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 @@ You might think that we could just as well write @code{(kill-buffer
 (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.)
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8feb8ea8c81..512d7d53019 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4394,8 +4394,7 @@ every 0.1 seconds.
   (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))
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index ded70f4927b..8d62ab87499 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2182,7 +2182,7 @@ Emacs is restarted by the session manager.
 
 @group
 (defun save-yourself-test ()
-  (insert "(save-excursion
+  (insert "(save-current-buffer
   (switch-to-buffer \"*scratch*\")
   (insert \"I am restored\"))")
   nil)
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index deded596f81..3897efc6f2b 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -806,7 +806,9 @@ after the completion of the excursion.
 
   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 @@ buffer and the values of point and the mark in it, evaluates
 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
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 91b65017754..7c3f91c3fa8 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3524,13 +3524,12 @@ following command:
 (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)
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 4f9f9c17369..d8ab347eebf 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1240,8 +1240,7 @@ foo
 
 @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