RE: `save-excursion' defeated by `set-buffer'

[Drew Adams]

> >> People will not naturally use `save-excursion' nowadays 
> >> just to save the current buffer.
> >
> > Maybe not naturally, no.  But thanks to the pressure of years of old
> > code flying around the web, they will do it nowadays on a regular
> > basis.  But indeed, thanks to threads like this one and to 
> > the warning I added, I hope I can reverse the trend.
> 
> Precisely, these warnings are not for people like you, Drew, or David.
> You guys have the experience necessary to make the correct choice.
> Warnings like this are *very* helpful to people like me, however, that
> have no experience with Emacs Lisp, but would like to write Elisp
> anyhow.

Actually, it is precisely people such as yourself who are done the greatest
disservice by this warning, IMHO.

> To be honest, for the purpose of teaching newbies it almost doesn't
> matter what the warning says either.  As long as it is clear that
> save-excursion and set-buffer are not to be used together then it is a
> win.

Et voila the damage done.  It is NOT true that "`save-excursion' and
`set-buffer' are not to be used together."  Even Stefan acknowledges that.  But
that's not the message that you (_clearly_) received.

> And yes, I realize that what I should do is read the manual umpteen
> million times, and memorize a pile of stuff.  Actually, in this case
> this might not be such a good idea.

Just read the doc string of `save-excursion' and you should be good to go.  It
tells you all you will ever need to know about it.  It tells you what
`save-excursion' _does_.  

The warning was supposedly designed to hint at what `save-excursion' does _not_
do, e.g., to prevent you from having unreasonable expectations that it will
restore more than it does.

> I assumed that I had picked up the save-excursion + set-buffer idiom
> while I was perusing the Gnus code, but in checking the manual I
> think that I might have picked it up from the /Introduction to
> Emacs Lisp/.  Using save-excursion and set-buffer together is covered in:
> 
>          4.4.3 `save-excursion' in `append-to-buffer'

Yes, please file a (doc) bug: the example in that section does not reflect the
latest definition of `append-to-buffer', which now uses `with-current-buffer'
instead of `set-buffer'.

That said, the code shown in that doc, which is just the Emacs 22 version of
`append-to-buffer', is not bad code.  It uses `set-buffer' instead of
`with-current-buffer', AND there is no harm in it (IMHO):

Emacs 22:
(save-excursion
  (set-buffer append-to) ; <======
  (setq point (point))
  (barf-if-buffer-read-only)
  (insert-buffer-substring oldbuf start end)
  (dolist (window windows)
    (when (= (window-point window) point)
      (set-window-point window (point))))))

Emacs 23+:
(save-excursion
  (with-current-buffer append-to ; <======
    (setq point (point))
    (barf-if-buffer-read-only)
    (insert-buffer-substring oldbuf start end)
    (dolist (window windows)
      (when (= (window-point window) point)
        (set-window-point window (point))))))

Do I prefer the latter (Emacs 23+)?  Yes.
Is the former dangerous or abominable?  No.

Does it even matter whether the BUFFER arg to `append-to-buffer' (which
corresponds to APPEND-TO above) happens to be the same as the `current-buffer'?
No.

Did this code _really need_ to be "fixed" to use `with-current-buffer' instead
of `set-buffer'?  No.  No danger, but it's still better with
`with-current-buffer'.