Rewrite the "Quitting Windows" section of Emacs Lisp Reference

* doc/lispref/windows.texi (Quitting Windows): Rewrite for
clarity.  (Bug#52328)

2 files changed, 126 insertions, 95 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index afb9dfcb9ec..c8f3b12080a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1648,9 +1648,10 @@ function will be interactive and will use the interactive spec of
 @var{function}.  One exception: if the interactive spec of @var{function}
 is a function (i.e., a @code{lambda} expression or an @code{fbound}
 symbol rather than an expression or a string), then the interactive
-spec of the combined function will be a call to that function with as sole
-argument the interactive spec of the original function.  To interpret the spec
-received as argument, use @code{advice-eval-interactive-spec}.
+spec of the combined function will be a call to that function with
+the interactive spec of the original function as sole argument.  To
+interpret the spec received as argument, use
+@code{advice-eval-interactive-spec}.
 
 Note: The interactive spec of @var{function} will apply to the combined
 function and should hence obey the calling convention of the combined function
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 54a5bce96c1..d988a0ff118 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4185,97 +4185,48 @@ action alist entry (@pxref{Buffer Display Action Alists}).
 
 @node Quitting Windows
 @section Quitting Windows
-
-When you want to get rid of a window used for displaying a buffer, you
-can call @code{delete-window} or @code{delete-windows-on}
-(@pxref{Deleting Windows}) to remove that window from its frame.  If the
-buffer is shown on a separate frame, you might want to call
-@code{delete-frame} (@pxref{Deleting Frames}) instead.  If, on the other
-hand, a window has been reused for displaying the buffer, you might
-prefer showing the buffer previously shown in that window, by calling the
-function @code{switch-to-prev-buffer} (@pxref{Window History}).
-Finally, you might want to either bury (@pxref{Buffer List}) or kill
-(@pxref{Killing Buffers}) the window's buffer.
-
-   The following command uses information on how the window for
-displaying the buffer was obtained in the first place, thus attempting
-to automate the above decisions for you.
+@cindex quitting windows
+
+After a command uses @code{display-buffer} to put a buffer on the
+screen, the user may decide to hide it and return to the previous
+configuration of the Emacs display.  We call that @dfn{quitting the
+window}.  The way to do this is to call @code{quit-window} while the
+window used by @code{display-buffer} is the selected window.
+
+The right way to restore the previous configuration of the display
+depends on what was done to the window where the buffer now appears.
+It might be right to delete that window, or delete its frame, or just
+display another buffer in that window.  One complication is that the
+user may have changed the window configuration since the act of
+displaying that buffer, and it would be undesirable to undo the user's
+explicitly requested changes.
+
+To enable @code{quit-window} to do the right thing,
+@code{display-buffer} saves information about what it did in the
+window's @code{quit-restore} parameter (@pxref{Window Parameters}).
 
 @deffn Command quit-window &optional kill window
 This command quits @var{window} and buries its buffer.  The argument
 @var{window} must be a live window and defaults to the selected one.
 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
-instead of burying it.  It calls the function @code{quit-restore-window}
-described next to deal with the window and its buffer.
+instead of burying it.
 
 @vindex quit-window-hook
-The functions in @code{quit-window-hook} are run before doing anything
-else.
+The function @code{quit-window} first runs @code{quit-window-hook}.
+Then it calls the function @code{quit-restore-window}, described next,
+which does the hard work.
 @end deffn
 
+You can get more control by calling @code{quit-restore-window} instead.
+
 @defun quit-restore-window &optional window bury-or-kill
 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 list specified by @var{window}'s @code{quit-restore}
-parameter (@pxref{Window Parameters}).
-
-The first element of the @code{quit-restore} parameter 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 only ever displayed this
-buffer; or @code{other}, the window showed another buffer before.
-@code{frame} and @code{window} affect how the window is quit, while
-@code{same} and @code{other} affect the redisplay of buffers
-previously shown in @var{window}.
-
-The parameter's second element is either one of the symbols
-@code{window} or @code{frame}, or a list whose elements are the buffer
-shown in @var{window} before, that buffer's window start and window
-point positions, and @var{window}'s height at that time.  If that
-buffer is still live when @var{window} is quit, then this function may
-reuse @var{window} to display it.
-
-The third element is the window selected at the time the parameter was
-created.  If this function deletes @var{window}, it subsequently tries
-to reselect the window named by that element.
-
-The fourth element is the buffer whose display caused the creation of
-this parameter.  This function may delete @var{window} if and only if
-it still shows that buffer.
-
-This function will try to delete @var{window} if and only if (1) the
-first element of its @code{quit-restore} parameter is either
-@code{window} or @code{frame}, (2) the window has no history of
-previously-displayed buffers and (3) the fourth element of the
-@code{quit-restore} parameter specifies the buffer currently displayed
-in @var{window}.  If @var{window} is part of an atomic window
-(@pxref{Atomic Windows}), it will try to delete the root of that
-atomic window instead.  In either case, it tries to avoid signaling an
-error when @var{window} cannot be deleted.
-
-If @var{window} shall be deleted, is the only window on its frame and
-there are other frames on that 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 the second element of the @code{quit-restore} parameter is a list
-of a buffer, a window start (@pxref{Window Start and End}) and a
-window point (@pxref{Window Point}), and that 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.  In either case, if @var{window} is not
-deleted, its @code{quit-restore} parameter is reset to @code{nil}.
+the selected one.  The function takes account of the @var{window}'s
+@code{quit-restore} parameter.
 
 The optional argument @var{bury-or-kill} specifies how to deal with
-@var{window}'s buffer.  The following values are handled:
+@var{window}'s buffer.  The following values are meaningful:
 
 @table @code
 @item nil
@@ -4285,25 +4236,106 @@ consequence, if @var{window} is not deleted, invoking
 
 @item append
 This means that if @var{window} is not deleted, its buffer is moved to
-the end of @var{window}'s list of previous buffers, so it's less likely
-that a future invocation of @code{switch-to-prev-buffer} will switch to
-it.  Also, it moves the buffer to the end of the frame's buffer list.
+the end of @var{window}'s list of previous buffers (@pxref{Window
+History}), so it's less likely that future invocations of
+@code{switch-to-prev-buffer} will switch to it.  Also, it moves the
+buffer to the end of the frame's buffer list (@pxref{Buffer List}).
 
 @item bury
 This means that if @var{window} is not deleted, its buffer is removed
-from @var{window}'s list of previous buffers.  Also, it moves the buffer
-to the end of the frame's buffer list.  This value provides the most
-reliable remedy to not have @code{switch-to-prev-buffer} switch to this
-buffer again without killing the buffer.
+from @var{window}'s list of previous buffers.  Also, it moves the
+buffer to the end of the frame's buffer list.  This is the most
+reliable way to prevent @code{switch-to-prev-buffer} from switching to
+this buffer again, short of killing the buffer.
 
 @item kill
 This means to kill @var{window}'s buffer.
 @end table
 
+The argument @var{bury-or-kill} also specifies what to do with
+@var{window}'s frame when @var{window} should be deleted, if it is the
+only window on its frame, and there are other frames on that frame's
+terminal.  If @var{bury-or-kill} equals @code{kill}, it means to
+delete the frame.  Otherwise, the fate of the frame is determined by
+calling @code{frame-auto-hide-function} (see below) with that frame as
+sole argument.
+
+This function always sets @var{window}'s @code{quit-restore} parameter
+to @code{nil} unless it deletes the window.
+@end defun
+
+The window @var{window}'s @code{quit-restore} parameter (@pxref{Window
+Parameters}) should be @code{nil} or a list of four elements:
+@c FIXME: describe what quit-restore-window does if this is nil.
+
+@lisp
+(@var{method} @var{obuffer} @var{owindow} @var{this-buffer})
+@end lisp
+
+The first element, @var{method}, is one of the four symbols
+@code{window}, @code{frame}, @code{same} and @code{other}.
+@code{frame} and @code{window} control how to delete @var{window},
+while @code{same} and @code{other} control displaying some other
+buffer in it.
+
+Specifically, @code{window} means that the window has been specially
+created by @code{display-buffer}; @code{frame} means that a separate
+frame has been created; @code{same}, that the window has only ever
+displayed this buffer; @code{other}, that the window showed another
+buffer before.
+
+The second element, @var{obuffer}, is either one of the symbols
+@code{window} or @code{frame}, or a list of the form
+
+@lisp
+(@var{prev-buffer} @var{prev-window-start} @var{prev-window-point} @var{height})
+@end lisp
+
+@noindent
+which says which buffer was shown in @var{window} before, that
+buffer's window start (@pxref{Window Start and End}) and window point
+(@pxref{Window Point}) positions at that time, and
+@var{window}'s height at that time.  If @var{prev-buffer} is still
+live when quitting @var{window}, quitting the window may reuse
+@var{window} to display @var{prev-buffer}.
+
+The third element, @var{owindow}, is the window that was selected
+just before the displaying was done.  If quitting deletes
+@var{window}, it tries to select @var{owindow}.
+
+The fourth element, @var{this-buffer}, is the buffer whose displaying
+set the @code{quit-restore} parameter.  Quitting @var{window} may delete
+that window only if it still shows that buffer.
+
+Quitting @var{window} tries to delete it if and only if (1)
+@var{method} is either @code{window} or @code{frame}, (2) the window
+has no history of previously-displayed buffers and (3)
+@var{this-buffer} equals the buffer currently displayed in
+@var{window}.  If @var{window} is part of an atomic window
+(@pxref{Atomic Windows}), quitting will try to delete the root of that
+atomic window instead.  In either case, it tries to avoid signaling an
+error when @var{window} cannot be deleted.
+
+If @var{obuffer} is a list, and @var{prev-buffer} is still live,
+quitting displays @var{prev-buffer} in @var{window} according to the
+rest of the elements of @var{obuffer}.  This includes resizing the
+window to @var{height} if it was temporarily resized to display
+@var{this-buffer}.
+
+Otherwise, if @var{window} was previously used for displaying other
+buffers (@pxref{Window History}), the most recent buffer in that
+history will be displayed.
+
+@ignore
+@c FIXME: Should we document display-buffer-reuse-window?
+If we document display-buffer-record-window, it should be with @defun.
+And maybe not here.
+
+
 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 for displaying
-@var{buffer} in @var{window}:
+the @code{quit-restore} window parameter correctly.  You can also set
+it manually, using the following code for displaying @var{buffer} in
+@var{window}:
 
 @example
 @group
@@ -4317,11 +4349,10 @@ possible to set it manually, using the following code for displaying
 
 Setting the window history to @code{nil} ensures that a future call to
 @code{quit-window} can delete the window altogether.
+@end ignore
 
-@end defun
-
-The following option specifies how to deal with a frame containing just
-one window that should be either quit, or whose buffer should be buried.
+The following option specifies a function to do the right thing with a
+frame containing one window when quitting that window.
 
 @defopt frame-auto-hide-function
 The function specified by this option is called to automatically hide
@@ -4350,7 +4381,6 @@ that frame's @code{auto-hide-function} frame parameter (@pxref{Frame
 Interaction Parameters}).
 @end defopt
 
-
 @node Side Windows
 @section Side Windows
 @cindex side windows