Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

martin rudalics <address@hidden> writes:

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

Okay, I got distracted for a while there, but here's another version. I
reworked the `quit-restore-window' section, and now it makes sense to
me, at any rate. I'm fairly uncertain about this paragraph:

The window is deleted entirely if: 1) the first element of the
@code{quit-restore} parameter is one of 'window or 'frame, 2) the
window has no history of previously-displayed buffers, and 3) the
displayed buffer matches the one in the fourth element of the
@code{quit-restore} parameter.  The window will never be deleted,
however, if it is the only one in its frame.  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.

I just don't see how/where the `bury-or-kill' parameter affects the
handling of the frame, I think it only affects the buffer. But I may
have "fixed" it until it doesn't make sense :)

I added a line about 'same as the first element of `quit-restore', but
it might be wrong.

I didn't add anything new about the 'other symbol. I see it getting set
in `display-buffer-record-window', but I don't see that it ever gets
used.

Hope this is nearly there,
Eric

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index a4f8400170..1577ac2f30 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
@@ -2994,27 +2995,37 @@ Quitting Windows
 @end deffn
 
 @defun quit-restore-window &optional window bury-or-kill
-This function tries to restore the state of @var{window} that existed
-before its buffer was displayed in it.  The optional argument
address@hidden must be a live window and defaults to the selected one.
+This function handles @var{window} and its buffer after quitting.  The
+optional argument @var{window} must be a live window and defaults to
+the selected one. The function's behavior is determined by the four
+elements of the @code{quit-restore} window parameter (@pxref{Window
+Parameters}), which is set to nil afterwards.
+
+The window is deleted entirely if: 1) the first element of the
address@hidden parameter is one of 'window or 'frame, 2) the
+window has no history of previously-displayed buffers, and 3) the
+displayed buffer matches the one in the fourth element of the
address@hidden parameter.  The window will never be deleted,
+however, if it is the only one in its frame.  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
address@hidden (see below) with that frame as sole
+argument.
 
-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.
-
-Otherwise, this function tries to redisplay the buffer previously shown
-in @var{window}.  It also tries to restore the window start
-(@pxref{Window Start and End}) and point (@pxref{Window Point})
-positions of the previously shown buffer.  If, in addition,
+If the third element of the @code{quit-restore} parameter is a list of
+buffer, window start (@pxref{Window Start and End}), and point
+(@pxref{Window Point}), and the buffer is still live, the buffer will
+be displayed, and start and point set accordingly.  If, in addition,
 @var{window}'s buffer was temporarily resized, this function will also
 try to restore the original height of @var{window}.
 
+Otherwise, if @var{window} was previously used for displaying other
+buffers (@pxref{Window History}), the most recent buffer in that
+history will be displayed.
+
 The cases described so far require that the buffer shown in @var{window}
 is still the buffer displayed by the last buffer display function for
 this window.  If another buffer has been shown in the meantime, or the
@@ -3048,9 +3059,24 @@ Quitting Windows
 This means to kill @var{window}'s buffer.
 @end table
 
address@hidden bases its decisions on information stored in
address@hidden's @code{quit-restore} window parameter (@pxref{Window
-Parameters}), and resets that parameter to @code{nil} after it's done.
+Typically, the display routines run by @code{display-buffer} will set
+the @code{quit-restore} window parameter correctly.  It's also
+possible to set it manually, using the following code when displaying
+``buffer'' in ``window'':
+
address@hidden
address@hidden
+(display-buffer-record-window type window buffer)
+
+(set-window-buffer window buffer)
+
+(set-window-prev-buffers window nil)
address@hidden group
address@hidden example
+
+The final use of @code{set-window-prev-buffers} ensures that a future
+call to @code{quit-window} will delete the window altogether.
+
 @end defun
 
 The following option specifies how to deal with a frame containing just
@@ -4845,25 +4871,32 @@ Window Parameters
 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
 (@pxref{Quitting Windows}).  It contains four elements:
 
-The first element is one of the symbols @code{window}, meaning that the
-window has been specially created by @code{display-buffer}; @code{frame},
-a separate frame has been created; @code{same}, the window has
-displayed the same buffer before; or @code{other}, the window showed
-another buffer before.
+The first element is one of the symbols @code{window}, meaning that
+the window has been specially created by @code{display-buffer};
address@hidden, a separate frame has been created; @code{same}, the
+window has only ever displayed this buffer; or @code{other}, the
+window showed another buffer before. The 'frame and 'window elements
+affect how the window is quit, while 'same affects the redisplay of
+buffers in this window.
 
 The second element is either one of the symbols @code{window} or
 @code{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.
+and the window's height at that time.  If that buffer is still live
+when the window is quit, then the function @code{quit-restore-window}
+re-uses the window to display the buffer.
 
 The third element is the window selected at the time the parameter was
-created.  The function @code{quit-restore-window} tries to reselect that
-window when it deletes the window passed to it as argument.
+created.  @code{quit-restore-window} tries to reselect that window if
+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.
 
+See the description of @code{quit-restore-window} in @ref{Quitting
+Windows} for details.
+
 @item @code{window-side} @code{window-slot}
 These parameters are used for implementing side windows (@pxref{Side
 Windows}).
@@ -4894,9 +4927,6 @@ Window Parameters
 versions of Emacs.
 @end table
 
-The @code{window-atom} parameter is used for implementing atomic windows.
-
-
 @node Window Hooks
 @section Hooks for Window Scrolling and Changes
 @cindex hooks for window operations