bug#12075: 24.1; doc out of date, unclear wrt *-selected-* and save-window-excursion

[Drew Adams]

You closed bug #7728, where the following doc problem was reported,
without taking care of it.  Anyway, it makes sense for this problem to
constitute a separate bug report from the report of a crash.
 
>From bug #7728:
 
> > > > `save-window-excursion' is the macro never to use.  It should be
> > > > used exclusively for debugging and prototyping.  Application
> > > > programmers who prefer to work with multiple frames themselves
> > > > should know best and avoid `save-window-excursion' like the
> > > > plague.  At least in "released" code.  Anything else is
> > > > masochism.
> > >
> > > I wonder how that particular plague escaped the attention of
> > > Richard et al for 35 years?  It's a wonder that it was ever
> > > documented, except perhaps as a mortal danger.
> >
> > 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.
 
That was back in January 2011.  A year and a half and one major release
later, the doc situation is still the same.
 
`with-selected-window' and `with-selected-frame' are hardly mentioned in
the Elisp manual.  On the other hand, `save-window-excursion' - "the
macro never to use" - is all over the manual, along with various
guidelines for its use.
 
Please fix the doc in accordance with your informed, up-to-date
understanding of what the differences, relative advantages, dangers,
etc. are.  Please compare and contrast, in usage terms useful to an
Elisp programmer.
 
In sum, please correct the doc and clear this up.
 
In GNU Emacs 24.1.1 (i386-mingw-nt5.1.2600)
 of 2012-06-10 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'