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.

10 files changed, 42 insertions, 27 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
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 27c376f764c..cabec8f7fb1 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2010-01-04  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * gnus.texi (Posting Styles): Use with-current-buffer.
+        * calc.texi (Defining Simple Commands): Prefer save-current-buffer.
+
 2010-01-02  Kevin Ryde  <user42@zip.com.au>
 
         * 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.
 
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index c88bb3e9ab8..e7c03197704 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -31968,7 +31968,7 @@ the function with code that looks roughly like this:
 @smallexample
 (let ((calc-command-flags nil))
   (unwind-protect
-      (save-excursion
+      (save-current-buffer
         (calc-select-buffer)
         @emph{body of function}
         @emph{renumber stack}
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index e90789d2494..a33a91ba6f1 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -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 @@ So here's a new example:
          (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"))))