Re: Manual suggestions for quit-restore documentation

[martin rudalics <rudalics@gmx.at>]

 > I've attached a diff with my edits; if/when some version of this is
 > eventually approved I can do a proper commit.

Thanks.  Please install.

 > I didn't add anything in the Window Parameters section about the first
 > two elements of the quit-restore parameter, simply because I don't
 > understand them well enough. I still think something should be said
 > there about how they influence quit behavior, though -- this is the
 > first place that people will look to find out how this works, and the
 > current docs are very clear about "what", but beg the question of "why".

Trying to recall.

      The first element is one of the symbols `window', meaning that the
      window has been specially created by `display-buffer'; `frame', a
      separate frame has been created; `same', the window has displayed
      the same buffer before; or `other', the window showed another
      buffer before.

If the first element is `window', we usually want to delete that window
but have to cater for a few special cases: For example, the window might
have become the only window on its frame since it was created in which
case we cannot simply delete the frame.  Or, the user might have
switched to another buffer in it in which case calling ‘quit-window’
probably should do just nothing.

If the first element is `frame', the situation is similar to the former
just that we now have to cater for the case that the window is no more
the only one on its frame in which case the frame should probably not be
deleted.

`same' is more tricky: We want to do certain things only if a window
always displayed the same buffer.  For example, automatic resizing of
the *help* window (via ‘temp-buffer-resize-mode’) should happen only if
that window was created specially for *help* and was subsequently reused
for *help* only.  If the *help* window was showing another buffer before
or in between, no such resizing should occur.

`other' signals more or less that the user has restricted the way new
pop-up windows/frames can be created and the (typically second on the
frame) window was (and probably will be) used for showing another
buffer.  In this case we usually do not delete the window, even if after
a sequence of `quit-window' calls the first buffer ever shown in that
window reappeared (we do not remember that much).

      The second element is either one of the symbols `window' or
      `frame', or a list whose elements are the buffer shown in the
      window before, that buffer's window start and window point
      positions, and the window's height at that time.

The values `window' and `frame' for the second element are redundant
IIRC.  Maybe we could as well leave them nil.  Iff the second element is
a list, it tells how to show the "other" buffer that was shown in that
window before when the window is quit.  That's important when that other
buffer appears in yet another window at the time of quitting - we may
want to restore the old `window-point' and `window-start' position, if
possible.

martin