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

[Uday S Reddy <u.s.reddy@cs.bham.ac.uk>]

On 3/13/2011 6:27 PM, Drew Adams wrote:

>> 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.
>
> No, someone simply pointed out that the Lisp manual does not say what you were
> trying to make it say.  What it says is correct.  It just hasn't yet been purged
> of `save-excursion' the way you would like.  And that's a good thing.

I wasn't trying to settle the dispute in the manual, which is not the 
place for it anyway.  The point is merely to make it faithful to the 
compiler and put enough helpful text for people that would be mystified 
by the new compiler warning.

The Current Buffer section has not been updated after the compiler 
warning was introduced.  So, it does need revision.  In particular, it 
contradicts the compiler warning by saying explicitly that one can use 
save-excursion whereas the compiler says no.

>> 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.
>
> My comment is to please leave it as it was.

We can't, because it contradicts the compiler.

> You have replaced mention of using `save-excursion' or `save-current-buffer'
> when one uses `set-buffer' with just mention of using `save-current-buffer' with
> it.  Both can be useful here.

No, the compiler complains about save-excursion being used for this purpose.

> You've added this:
>
> "However, it is not a recommended use of `save-excursion' for reverting buffer
> changes."
>
> The word "it" references nothing here - no meaning.

If you really want "it" to refer to something, think of "it" as the 
compiler.

> And `save-excursion' is not about reverting buffer changes - never has been.
> And no one would ever think that it is.  And the warning you then try to explain
> also has nothing to do with reverting buffer changes.

But this section is about buffer changes.  And, in any case, the 
sentence before the one you quoted says:

   "save-excursion restores the current buffer and, in addition, 
restores the point and mark in that buffer as well."

> And your explanation of the warning, like the warning itself, does not help.

Since you think the warning doesn't help, I am not surprised that you 
don't find the explanation helpful.  But, perhaps, you can be a bit more 
objective here?  In what way does it not help?

> And in your "recommended practice" section, you completely miss that
> `save-excursion' is not only about restoring point (and mark).  It is
> specifically designed to restore `current-buffer' as well.
>
> And there should be no "there should be"s in technical doc:
>
> "there should be no calls to `set-buffer' in the intervening code
>   inside the `save-excursion' form before the changes to point or mark,"
>
> Nonsense.  Let's help users understand, not just give them a catechism to follow
> blindly.
>
> "because `save-excursion' only restores the point and mark of
>   the current buffer, not for the other buffers that may be the target
>   of `set-buffer'"
>
> Doesn't follow at all.

It does follow.  Here is the logic, spelled out:

1. save-excursion should be placed as close as possible to the 
point/mark-movements.

2. save-excursion only restores the current buffer's point/mark.

So, if there is a set-buffer between the save-excursion and the 
point/mark-movements, then it is not as close as possible to the 
point/mark-movements.  (In fact, in the normal cases where the 
set-buffer's are not no-op's , there would have to be at least *two* 
set-buffer's between the save-excursion and the point/mark-movements 
that it is reverting.)

> This is getting sillier and sillier.  All because of a warning that no one can
> decipher and the explanations for which go round and round...nowhere.

Sorry, I have been able to decipher it just fine.  On the other hand, I 
haven't been able to decipher what your objection is about.  So, we 
could perhaps make some progress if you can help me understand your 
objection.  If it is just a political position on what compilers should 
or should not do, I couldn't be interested because I didn't write the 
compiler.  But if there is a technical point, what is it?

Cheers,
Uday