From b5354e989d8ec590ef6160f9241333a7d73628e3 Mon Sep 17 00:00:00 2001 From: Richard Stallman Date: Tue, 7 Dec 2021 23:35:31 -0500 Subject: [PATCH] Rewrite the "Quitting Windows" section of Emacs Lisp Reference * doc/lispref/windows.texi (Quitting Windows): Rewrite for clarity. (Bug#52328) --- doc/lispref/functions.texi | 7 +- doc/lispref/windows.texi | 214 +++++++++++++++++++++---------------- 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 -- 2.39.2