bug#7728: 24.0.50; GDB backtrace from abort

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

> > I wonder how that particular plague escaped the attention of Richard
> > et al for 35 years?
> 
> Hmm... last I checked, we're only up to 25 years.

We who?  Emacs != Gnu Emacs.  Emacs dev began in the mid-70s.

No, I don't know when `save-window-excursion' was introduced.  And yes, I would
guess that it was introduced before Emacs frames were introduced.  Still, it's
been a very long time now, no matter how you count it.

> As for how... easy: they only use a single frame, and in that 
> setting it works fine and makes perfect sense.  But it doesn't
> extend well to situations with multiple frames.

I won't argue against that.  I'm not knowledgable about it.

If you are sure of what you say, then I suggest that you update the doc that
tells users how to use `save-window-excursion', including together with
`save-excursion'.  `save-window-excursion' is all through the Elisp manual, and
`with-selected-frame' is not mentioned even once!

The new doc should not just cover the case where you switch windows in the same
frame or you switch frames, but the more general case where you do not know
whether some other window and frame will be selected by the wrapped code.

IOW, if you replace or add to the doc about using `save-window-excursion', then
do so in a way that is just as general.

See also the multiple caveats in the doc about `save-window-excursion', to see
whether they too need to be updated to also mention `with-selected-frame' or
`with-selected-window'.

It would be very helpful if in the doc you compared and contrasted the proper
use of `save-selected-window', `with-selected-window', `with-selected-frame, and
`save-window-excursion', pointing out when to use which, what their differences
are, gotchas, etc.  That's not clear, IMO.


In any case, knowing how to use `with-selected-frame', perhaps together with
`with-selected-window', will not help my code, which needs to support Emacs
versions that do not have these macros.  Still, I would like the doc to be
updated to make things clear.