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

["Drew Adams" <drew.adams@oracle.com>]

> 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.

> 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.

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.

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.

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.

And your explanation of the warning, like the warning itself, does 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.  That certainly is not a reason not to use `set-buffer'
in the body of `save-excursion' before any point movements.  No connection.  In
your "because A", A is true - so what?  It does not follow that you should not
move point in buffer X after calling (set-buffer X).

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.

This is how we end up with "guidance" in the manual that is later pointed to as
proof, The Word, and is hammered into user heads as a catechism.  This is
obviously a controversial area where judgments differ and programmer judgment is
called for.  Please do not try to carve one view of this in stone.

Just give users the facts of what these functions do, and let them decide for
themselves whether and how to use them.  Users are not idiots, in general.

Underlying your attempt to revise the manual here, your real contribution is in
underlining that this message is incomprehensible and unhelpful on its own.  The
right solution is to get rid of the misguided message, IMO.