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

["Drew Adams" <drew.adams@oracle.com>]

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