bug#9979: 24.0.91; doc string of `save-window-excursion'

bug#9979: 24.0.91; doc string of `save-window-excursion'

[Drew Adams]

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"'
 

bug#9979: 24.0.91; doc string of `save-window-excursion'

[Stefan Monnier]

> 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

bug#9979: 24.0.91; doc string of `save-window-excursion'

[Drew Adams]

> > 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.

bug#9979: 24.0.91; doc string of `save-window-excursion'

[Chong Yidong]

"Drew Adams" <drew.adams@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.