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

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

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