GNU bug report logs -
#9979
24.0.91; doc string of `save-window-excursion'
Previous Next
Reported by: "Drew Adams" <drew.adams <at> oracle.com>
Date: Sun, 6 Nov 2011 23:03:01 UTC
Severity: minor
Found in version 24.0.91
Done: Chong Yidong <cyd <at> gnu.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9979 in the body.
You can then email your comments to 9979 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#9979
; Package
emacs
.
(Sun, 06 Nov 2011 23:03:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
"Drew Adams" <drew.adams <at> oracle.com>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Sun, 06 Nov 2011 23:03:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
This recent addition to the doc string is misleading and not helpful:
BEWARE: Most uses of this macro introduce bugs.
E.g. it should not be used to try and prevent some code from opening
a new window, since that window may sometimes appear in another frame,
in which case `save-window-excursion' cannot help.
For one thing, we should not be saying "BEWARE" in the doc. "Note:" is
sufficient, and in most cases even that is superfluous. Just get
directly to the point.
More importantly, "most uses" means what here? Are you really
suggesting that most of the existing uses of this macro introduce bugs?
This is silly. If you really have something of substance to say - to
"warn" people about, then get directly to the point and say it. Stop
trying to add force by ornamenting this doc with vague warnings of
hobgoblins.
The following point appears to be the _only_ real content in this
paragraph: Do not use this to try to prevent opening a new window,
since...
But that too does not really say what you want (IIUC). No one would use
this to try to _prevent_ opening a new window. But someone might use it
in hopes of saving and restoring the configuration that existed before
a new window was opened.
And that's what the advice here is all about: Because this macro
restores only the window config for the selected frame, it has no effect
on changes to other frames, including addition of new windows to other
frames or the deletion of windows from other frames.
Just say that, and forget all the mumbo jumbo about BEWARE and
introduction of bugs: Like all window-config functions and macros, this
macro has no effect on windows in other frames.
In GNU Emacs 24.0.91.1 (i386-mingw-nt5.1.2600) of 2011-10-30 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.6) --no-opt --cflags
-I"D:/devel/emacs/libs/libXpm-3.5.8/include"
-I"D:/devel/emacs/libs/libXpm-3.5.8/src"
-I"D:/devel/emacs/libs/libpng-dev_1.4.3-1/include"
-I"D:/devel/emacs/libs/zlib-dev_1.2.5-2/include"
-I"D:/devel/emacs/libs/giflib-4.1.4-1/include"
-I"D:/devel/emacs/libs/jpeg-6b-4/include"
-I"D:/devel/emacs/libs/tiff-3.8.2-1/include"
-I"D:/devel/emacs/libs/gnutls-2.10.1/include" --ldflags
-L"D:/devel/emacs/libs/gnutls-2.10.1/lib"'
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#9979
; Package
emacs
.
(Mon, 07 Nov 2011 13:53:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 9979 <at> debbugs.gnu.org (full text, mbox):
> Are you really
> suggesting that most of the existing uses of this macro introduce bugs?
Yes.
> But that too does not really say what you want (IIUC). No one would use
> this to try to _prevent_ opening a new window.
This No one seems to write an awful lot of Elisp code, sadly.
Stefan
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#9979
; Package
emacs
.
(Mon, 07 Nov 2011 16:38:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 9979 <at> debbugs.gnu.org (full text, mbox):
> > The following point appears to be the _only_ real content
> > in this paragraph: Do not use this to try to prevent opening
> > a new window, since...
> >
> > But that too does not really say what you want (IIUC). No
> > one would use this to try to _prevent_ opening a new window.
>
> This No one seems to write an awful lot of Elisp code, sadly.
If you think that, then it is OK to add that to a list of things you want to
mention that the macro does _not_ do. But it is not adequate to state _only_
that, as the doc for the macro. That's pretty much what is happening here.
It is not even adequate to state only a whole list of things that the macro does
_not_ do. In any case, most important for such a list would be to mention that
the macro has no effect on windows in other frames.
Above all, the doc needs to state what the macro _does_ do. There, the doc
string falls down. See the Elisp manual for a better and more succinct
explanation of what the macro does.
The first line of the doc string is also incorrect. The macro does not
"preserve" window sizes and contents. Preserving implies that these do not
change at any time during the macro call. It does not preserve these, but it
_restores_ them, after they have perhaps been changed by the BODY. And again,
it's important to mention that it is only the windows of the selected frame (not
other frames) that are restored.
A statement that the macro "preserves" a window config is in fact _precisely_
the kind of thing that can lead users to think that it _prevents_ opening a new
window. Preserving the config would indeed prevent new windows opening.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#9979
; Package
emacs
.
(Sun, 11 Mar 2012 16:47:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 9979 <at> debbugs.gnu.org (full text, mbox):
"Drew Adams" <drew.adams <at> oracle.com> writes:
> The macro does not "preserve" window sizes and contents. Preserving
> implies that these do not change at any time during the macro call.
> It does not preserve these, but it _restores_ them, after they have
> perhaps been changed by the BODY. And again, it's important to
> mention that it is only the windows of the selected frame (not other
> frames) that are restored.
I've fixed the docstring. Thanks.
bug closed, send any further explanations to
9979 <at> debbugs.gnu.org and "Drew Adams" <drew.adams <at> oracle.com>
Request was from
Chong Yidong <cyd <at> gnu.org>
to
control <at> debbugs.gnu.org
.
(Sun, 11 Mar 2012 16:47:03 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Mon, 09 Apr 2012 11:24:04 GMT)
Full text and
rfc822 format available.
This bug report was last modified 12 years and 43 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.