save-excursion and save-current-buffer - edits to the manual

[Uday S Reddy]

The debate on save-excursion getting "defeated" flared up again on
gnu.emacs.help.  Somebody noticed that the Lisp manual hasn't been
updated properly to take account of the new compiler warning.

The attached patch/bundle is an attempt to explain the situation as
well as to provide guidance on how to use these forms correctly.
Please let me have any comments.

Cheers,
Uday

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: address@hidden
# target_branch: file:///D:/gnu/emacs-23-dev/
# testament_sha1: 2bb9efa1bb4c2102b3bb3a153847419b08046134
# timestamp: 2011-03-13 16:09:13 +0000
# base_revision_id: address@hidden
# 
# Begin patch
=== modified file 'doc/lispref/buffers.texi'
--- doc/lispref/buffers.texi    2011-01-02 23:50:46 +0000
+++ doc/lispref/buffers.texi    2011-03-13 16:08:41 +0000
@@ -113,8 +113,8 @@
 as well as from the command loop; it is convenient for the caller if
 the subroutine does not change which buffer is current (unless, of
 course, that is the subroutine's purpose).  Therefore, you should
-normally use @code{set-buffer} within a @code{save-current-buffer} or
address@hidden (@pxref{Excursions}) form that will restore the
+normally use @code{set-buffer} within a @code{save-current-buffer}
+that will restore the 
 current buffer when your function is done.  Here, as an example, is a
 simplified version of the command @code{append-to-buffer}:
 
@@ -149,8 +149,8 @@
 binding's scope.  Otherwise you might bind it in one buffer and unbind
 it in another!  There are two ways to do this.  In simple cases, you may
 see that nothing ever changes the current buffer within the scope of the
-binding.  Otherwise, use @code{save-current-buffer} or
address@hidden to make sure that the buffer current at the
+binding.  Otherwise, use @code{save-current-buffer}
+to make sure that the buffer current at the
 beginning is current again whenever the variable is unbound.
 
   Do not rely on using @code{set-buffer} to change the current buffer
@@ -171,6 +171,36 @@
 Using @code{save-current-buffer}, as we did, handles quitting, errors,
 and @code{throw}, as well as ordinary evaluation.
 
+Sometimes the @code{save-excursion} (@pxref{Excursions}) form is used
+instead of @code{save-current-buffer} to restore the current-buffer.
address@hidden restores the current buffer and, in addition,
+restores the point and mark in that buffer as well.  However, it is
+not a recommended use of @code{save-excursion} for reverting buffer
+changes.  If you use it, the byte compiler gives the somewhat
+mysterious warning:
+
address@hidden
+Warning: @code{save-excursion} defeated by @code{set-buffer}
address@hidden example
+
address@hidden The reasons for the warning are:
+
address@hidden
address@hidden 
+The @code{save-excursion} only restores the original buffer's point and
+mark, not in the target of the @code{set-buffer}.
address@hidden
+If the body of the @code{save-excursion} somehow changes the original
+buffer's point and mark,  then it is best to place
address@hidden around the portion of the code that does so.
address@hidden itemize
+
address@hidden Replacing @code{save-excursion} by
address@hidden is always a good way to get around the
+compiler warning.  However, before you can do the replacement, you
+will need to ensure that all the changes to the point and mark inside
+the body are properly protected by @code{save-excursion} forms.
+
 @defun current-buffer
 This function returns the current buffer.
 

=== modified file 'doc/lispref/positions.texi'
--- doc/lispref/positions.texi  2011-01-02 23:50:46 +0000
+++ doc/lispref/positions.texi  2011-03-13 16:08:41 +0000
@@ -808,7 +808,7 @@
 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
 Configurations}).  When only the identity of the current buffer needs
 to be saved and restored, it is preferable to use
address@hidden instead.
address@hidden instead.  (see @ref{Current Buffer}).
 
 @defspec save-excursion address@hidden
 @cindex mark excursion
@@ -867,6 +867,25 @@
 @code{deactivate-mark}, and thus causing the deactivation of the mark
 after the command finishes.  @xref{The Mark}.
 
+  It is recommended practice to place @code{save-excursion} as close
+as possible to the portions of code that change the point or mark.  In
+particular, there should be no calls to @code{set-buffer} in the
+intervening code inside the @code{save-excursion} form before the
+changes to point or mark, because @code{save-excursion} only restores the point
+and mark of the current buffer, not for the other buffers that may be
+the target of @code{set-buffer}.  If a @code{save-excursion} form
+begins with a call to @code{set-buffer}, the byte compiler
+produces the warning:
+
address@hidden
+Warning: @code{save-excursion} defeated by @code{set-buffer}
address@hidden example
+
address@hidden You may replace the @code{save-excursion} forms by
address@hidden forms to get around the warning, but you
+would also need to ensure that the changes to point and mark in the
+target buffers are protected by @code{save-excursion} forms locally.
+
 @node Narrowing
 @section Narrowing
 @cindex narrowing

# Begin bundle
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
BBbAf4u5IpwoSAB4/wCA