From c153250adb1c4881cd775623028e793abea7b5fa Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Mon, 3 Jun 2019 10:36:00 +0200 Subject: [PATCH] Try to improve text on atomic windows in Elisp manual * doc/lispref/windows.texi (Deleting Windows): Mention how 'delete-window' and 'delete-other-windows' handle atomic windows. Minor rewrite. (Quitting Windows): Mention how 'quit-restore-window' handles atomic windows and that it tries to avoid raising an error. (Atomic Windows): Tell how to dissolve atomic windows. --- doc/lispref/windows.texi | 83 ++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 34 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f4395c12d26..b2dd3d99583 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1307,8 +1307,10 @@ the selected window. If deleting the window would leave no more windows in the window tree (e.g., if it is the only live window in the frame) or all remaining -windows on @var{window}'s frame are side windows (@pxref{Side Windows}), -an error is signaled. +windows on @var{window}'s frame are side windows (@pxref{Side +Windows}), an error is signaled. If @var{window} is part of an atomic +window (@pxref{Atomic Windows}), this function tries to delete the +root of that atomic window instead. By default, the space taken up by @var{window} is given to one of its adjacent sibling windows, if any. However, if the variable @@ -1327,10 +1329,13 @@ Parameters}. @end deffn @deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame, deleting other windows -as necessary. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. An error is signaled if @var{window} is a side -window (@pxref{Side Windows}). The return value is @code{nil}. +This function makes @var{window} fill its frame, deleting other +windows as necessary. If @var{window} is omitted or @code{nil}, it +defaults to the selected window. An error is signaled if @var{window} +is a side window (@pxref{Side Windows}). If @var{window} is part of +an atomic window (@pxref{Atomic Windows}), this function tries to make +the root of that atomic window fill its frame. The return +value is @code{nil}. The behavior of this function may be altered by the window parameters of @var{window}, so long as the variable @code{ignore-window-parameters} is @@ -3909,9 +3914,8 @@ described next to deal with the window and its buffer. 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 the @code{quit-restore} window -parameter (@pxref{Window Parameters}), which is set to @code{nil} -afterwards. +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 @@ -3920,35 +3924,40 @@ 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 this window. +previously shown in @var{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. If that buffer is still live -when the window is quit, then the function @code{quit-restore-window} -reuses the window to display the buffer. +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 @code{quit-restore-window} deletes the window passed to -it as argument, it then tries to reselect this window. +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. @code{quit-restore-window} deletes the specified window -only if it still shows that buffer. - -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. 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. +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 third element of the @code{quit-restore} parameter is a list of buffer, window start (@pxref{Window Start and End}), and point @@ -3959,7 +3968,8 @@ 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. +history will be displayed. In either case, if @var{window} is not +deleted, its @code{quit-restore} parameter is reset to @code{nil}. The optional argument @var{bury-or-kill} specifies how to deal with @var{window}'s buffer. The following values are handled: @@ -4440,6 +4450,11 @@ parameter assigned by @code{display-buffer-in-atom-window}. Further parameters have to be set by the application explicitly via a @code{window-parameters} entry in @var{alist}. + Atomic windows automatically cease to exist when one of their +constituents gets deleted. To dissolve an atomic window manually, +reset the @code{window-atom} parameter of its constituents---the root +of the atomic window and all its descendants. + The following code snippet, when applied to a single-window frame, first splits the selected window and makes the selected and the new window constituents of an atomic window with their parent as root. It -- 2.39.2