Manual suggestions for quit-restore documentation

[Eric Abrahamsen <eric@ericabrahamsen.net>]

[-- Attachment #1: Type: text/plain, Size: 708 bytes --]

As mentioned in a thread in emacs.help, I've got some suggestions for
the parts of the Elisp manual that touch on the quit-restore window
parameter, and its behaviors.

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

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

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: windowsdoc.diff --]
[-- Type: text/x-patch, Size: 3320 bytes --]

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index affa28c920..504a74dfd1 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2803,12 +2803,13 @@ Window History
 @section Window History
 @cindex window history
 
-Each window remembers in a list the buffers it has previously displayed,
-and the order in which these buffers were removed from it.  This history
-is used, for example, by @code{replace-buffer-in-windows}
-(@pxref{Buffers and Windows}).  The list is automatically maintained by
-Emacs, but you can use the following functions to explicitly inspect or
-alter it:
+Each window remembers in a list the buffers it has previously
+displayed, and the order in which these buffers were removed from it.
+This history is used, for example, by @code{replace-buffer-in-windows}
+(@pxref{Buffers and Windows}), and when quitting windows
+(@pxref{Quitting Windows}).  The list is automatically maintained by
+Emacs, but you can use the following functions to explicitly inspect
+or alter it:
 
 @defun window-prev-buffers &optional window
 This function returns a list specifying the previous contents of
@@ -2998,15 +2999,17 @@ Quitting Windows
 before its buffer was displayed in it.  The optional argument
 @var{window} must be a live window and defaults to the selected one.
 
-If @var{window} was created specially for displaying its buffer, this
-function deletes @var{window} provided its frame contains at least one
-other live window.  If @var{window} is the only window on its frame and
-there are other frames on the frame's terminal, the value of the
-optional argument @var{bury-or-kill} determines how to proceed with the
-window.  If @var{bury-or-kill} equals @code{kill}, the frame is deleted
-unconditionally.  Otherwise, the fate of the frame is determined by
-calling @code{frame-auto-hide-function} (see below) with that frame as
-sole argument.
+If @var{window} was previously used for displaying other buffers
+(@pxref{Window History}), the most recent buffer in that history will
+be displayed.  If it has no history, this function deletes
+@var{window} altogether, provided its frame contains at least one
+other live window.  If @var{window} is the only window on its frame
+and there are other frames on the frame's terminal, the value of the
+optional argument @var{bury-or-kill} determines how to proceed with
+the window.  If @var{bury-or-kill} equals @code{kill}, the frame is
+deleted unconditionally.  Otherwise, the fate of the frame is
+determined by calling @code{frame-auto-hide-function} (see below) with
+that frame as sole argument.
 
 Otherwise, this function tries to redisplay the buffer previously shown
 in @var{window}.  It also tries to restore the window start
@@ -4857,8 +4860,9 @@ Window Parameters
 window when it deletes the window passed to it as argument.
 
 The fourth element is the buffer whose display caused the creation of
-this parameter.  @code{quit-restore-window} deletes the specified window
-only if it still shows that buffer.
+this parameter.  @code{quit-restore-window} deletes the specified
+window only if it still shows that buffer, and it has no history of
+previously-displayed buffers.
 
 @item @code{window-side} @code{window-slot}
 These parameters are used for implementing side windows (@pxref{Side