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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 12075 in the body.
You can then email your comments to 12075 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.1;
	doc out of date, unclear wrt *-selected-* and save-window-excursion
Date: Sat, 28 Jul 2012 08:00:19 -0700

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'

Message #8 received at 12075 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <12075 <at> debbugs.gnu.org>
Subject: RE: bug#12075: 24.1;
	doc out of date, unclear wrt *-selected-* and save-window-excursion
Date: Sun, 16 Sep 2012 16:38:49 -0700

ping

Message #11 received at 12075 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 12075 <at> debbugs.gnu.org
Subject: Re: bug#12075: 24.1; doc out of date, unclear wrt *-selected-* and
 save-window-excursion
Date: Tue, 01 Jun 2021 09:42:14 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> `with-selected-window' and `with-selected-frame' are hardly mentioned in
> the Elisp manual.

The former seems well-documented in Emacs 28, but the latter wasn't
mentioned at all, so I've fixed that now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.