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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: "Drew Adams" <drew.adams@HIDDEN>; dated Sat, 28 Jul 2012 15:08:01 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 12075 <at> debbugs.gnu.org:


Received: (at 12075) by debbugs.gnu.org; 16 Sep 2012 23:40:17 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Sep 16 19:40:17 2012
Received: from localhost ([127.0.0.1]:37672 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1TDORk-0005a3-E6
	for submit <at> debbugs.gnu.org; Sun, 16 Sep 2012 19:40:17 -0400
Received: from acsinet15.oracle.com ([141.146.126.227]:18575)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@HIDDEN>) id 1TDORi-0005Zw-M3
	for 12075 <at> debbugs.gnu.org; Sun, 16 Sep 2012 19:40:15 -0400
Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94])
	by acsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with
	ESMTP id q8GNd1iZ020992
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
	for <12075 <at> debbugs.gnu.org>; Sun, 16 Sep 2012 23:39:02 GMT
Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156])
	by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	q8GNd0pf017222
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
	for <12075 <at> debbugs.gnu.org>; Sun, 16 Sep 2012 23:39:00 GMT
Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64])
	by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id
	q8GNd0tP001834
	for <12075 <at> debbugs.gnu.org>; Sun, 16 Sep 2012 18:39:00 -0500
Received: from dradamslap1 (/10.159.170.142)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Sun, 16 Sep 2012 16:38:59 -0700
From: "Drew Adams" <drew.adams@HIDDEN>
To: <12075 <at> debbugs.gnu.org>
References: <24E7DF75481D4ABB9FB5939A3E6D5854@HIDDEN>
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
Message-ID: <CE9BCF9316394BD7862E7D170A08911E@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Mailer: Microsoft Office Outlook 11
In-Reply-To: <24E7DF75481D4ABB9FB5939A3E6D5854@HIDDEN>
Thread-Index: Ac1s0bRfaAeam5FVR8WqaiU5zyGtpAnkrNpw
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157
X-Source-IP: ucsinet22.oracle.com [156.151.31.94]
X-Spam-Score: -7.4 (-------)
X-Debbugs-Envelope-To: 12075
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -7.4 (-------)

ping





Information forwarded to bug-gnu-emacs@HIDDEN:
bug#12075; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 28 Jul 2012 15:07:40 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Jul 28 11:07:40 2012
Received: from localhost ([127.0.0.1]:46691 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Sv8cF-0005Io-M9
	for submit <at> debbugs.gnu.org; Sat, 28 Jul 2012 11:07:40 -0400
Received: from eggs.gnu.org ([208.118.235.92]:49310)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8cB-0005Ie-1S
	for submit <at> debbugs.gnu.org; Sat, 28 Jul 2012 11:07:37 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8VL-0005uH-6H
	for submit <at> debbugs.gnu.org; Sat, 28 Jul 2012 11:00:32 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_HI,
	UNPARSEABLE_RELAY autolearn=unavailable version=3.3.2
Received: from lists.gnu.org ([208.118.235.17]:39745)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8VL-0005uD-3D
	for submit <at> debbugs.gnu.org; Sat, 28 Jul 2012 11:00:31 -0400
Received: from eggs.gnu.org ([208.118.235.92]:34984)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8VJ-0001Xz-VZ
	for bug-gnu-emacs@HIDDEN; Sat, 28 Jul 2012 11:00:31 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8VI-0005tv-Rg
	for bug-gnu-emacs@HIDDEN; Sat, 28 Jul 2012 11:00:29 -0400
Received: from rcsinet15.oracle.com ([148.87.113.117]:46247)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1Sv8VI-0005tm-KV
	for bug-gnu-emacs@HIDDEN; Sat, 28 Jul 2012 11:00:28 -0400
Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238])
	by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with
	ESMTP id q6SF0QYJ010286
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
	for <bug-gnu-emacs@HIDDEN>; Sat, 28 Jul 2012 15:00:27 GMT
Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156])
	by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	q6SF0Qoq024302
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
	for <bug-gnu-emacs@HIDDEN>; Sat, 28 Jul 2012 15:00:26 GMT
Received: from abhmt120.oracle.com (abhmt120.oracle.com [141.146.116.72])
	by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id
	q6SF0Prs023472
	for <bug-gnu-emacs@HIDDEN>; Sat, 28 Jul 2012 10:00:26 -0500
Received: from dradamslap1 (/10.159.164.157)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Sat, 28 Jul 2012 08:00:25 -0700
From: "Drew Adams" <drew.adams@HIDDEN>
To: <bug-gnu-emacs@HIDDEN>
Subject: 24.1;
	doc out of date, unclear wrt *-selected-* and save-window-excursion
Date: Sat, 28 Jul 2012 08:00:19 -0700
Message-ID: <24E7DF75481D4ABB9FB5939A3E6D5854@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Mailer: Microsoft Office Outlook 11
Thread-Index: Ac1s0bRfaAeam5FVR8WqaiU5zyGtpA==
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157
X-Source-IP: acsinet22.oracle.com [141.146.126.238]
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1)
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3)
X-Received-From: 208.118.235.17
X-Spam-Score: -6.1 (------)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -6.1 (------)

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'






Acknowledgement sent to "Drew Adams" <drew.adams@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#12075; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

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