From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.bugs Subject: bug#52328: 27.2; [DOC] Paragraph about quit-restore-window Date: Tue, 07 Dec 2021 23:35:31 -0500 Message-ID: References: <87tufm0xcd.fsf@laposte.net> <83mtlcxnwi.fsf@gnu.org> Reply-To: rms@gnu.org Content-Type: text/plain; charset=Utf-8 Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4943"; mail-complaints-to="usenet@ciao.gmane.io" Cc: ke.vigouroux@laposte.net, 52328@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Dec 08 05:36:37 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1muoh1-0000xh-FX for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 08 Dec 2021 05:36:35 +0100 Original-Received: from localhost ([::1]:40468 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1muoh0-0004rI-6L for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 07 Dec 2021 23:36:34 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:39132) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muogb-0004mv-59 for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 23:36:09 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56038) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1muogU-0007N9-9Z for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 23:36:08 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1muogU-0004Yx-2Y for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 23:36:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Richard Stallman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 Dec 2021 04:36:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52328 X-GNU-PR-Package: emacs Original-Received: via spool by 52328-submit@debbugs.gnu.org id=B52328.163893814217512 (code B ref 52328); Wed, 08 Dec 2021 04:36:02 +0000 Original-Received: (at 52328) by debbugs.gnu.org; 8 Dec 2021 04:35:42 +0000 Original-Received: from localhost ([127.0.0.1]:39351 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muog9-0004YO-Vt for submit@debbugs.gnu.org; Tue, 07 Dec 2021 23:35:42 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:38184) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muog5-0004Y6-Kg for 52328@debbugs.gnu.org; Tue, 07 Dec 2021 23:35:41 -0500 Original-Received: from [2001:470:142:3::e] (port=42588 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muofz-0007Gt-Mx; Tue, 07 Dec 2021 23:35:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=Date:References:Subject:In-Reply-To:To:From: mime-version; bh=XBzxLfeoyRezFuR/mcrHINFfmyLGW2Mv3lkXRxshq40=; b=bkhuJ7efLDS6 7/Uci756chTWHn7dfX/UyeMq8XAcpVxKQ4L4YeDpM8bhdrLITbdN9pPd1Q0TIH3SsJM5QJTysVf0r kRNCzNR7q0zj1j3Qhsc9LSj+Yhm1CHlmAaIvuRF+Fim8CMPNyv5IVPRLr4R9cZ8KhvpbNuKsdFEj+ ZOf9GOt+W5CEtubqFVZ3816H/iEIs1BIhsYePdCx4WIn1+WNaEhJb8szyUVgEbZ4WAdNrewTXRiQI k2oT9eumsVUa3PHHmD46WuuAqn25eusbQV9sjLyTii+PSZ4HZwQzdov7HP3I2TWZbQd/jQKektyr+ AL4v9R3zjIaMbaWhjuwQMA==; Original-Received: from rms by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1muofz-0006Ij-H3; Tue, 07 Dec 2021 23:35:31 -0500 In-Reply-To: <83mtlcxnwi.fsf@gnu.org> (message from Eli Zaretskii on Tue, 07 Dec 2021 20:36:45 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:221906 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > It would be clearer to present the list using Lisp syntax: > > (@var{buffer} @var{window-start} @var{new-point}) > > Then it can talk about these values with their names, which > > is clearer. > That is true. But that's far from being the single or the main > problem of that description. I had seen only at what was in the email I replied to. > I invite you to read the entire description of this function. I just did that, and I agree it was very complex. In addition, it failed in many ways to follow Texinfo conventions and our style conventions. So I rewrote the whole node. I started with Master from Nov 1. It is still hard to read, but much less so than before. I left some loose ends where it is necessary to study the source code to know what to say. I marked them with @c ???. ====================================================================== @node Quitting Windows @section Quitting Windows @cindex quitting a window After a command uses @code{display-buffer} to put buffer on the screen, the user may decide to hide it and return to the previous screen configuration. We call that @dfn{quitting the window}. The way to do this is to call @code{quit-window}. The right way to restore the old screen configuration 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}). @c ??? Should quit-restore be in some index? @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. @c ??? Does quit-restore-window call this hook? @vindex quit-window-hook 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 taks 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 meaningful: @table @code @item nil This means to not deal with the buffer in any particular way. As a consequence, if @var{window} is not deleted, invoking @code{switch-to-prev-buffer} will usually show the buffer again. @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 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. @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 is the most reliable way to prevent @code{switch-to-prev-buffer} from switching to this buffer 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 ??? What does quit-restore-window do if this is nil? Nothing? @lisp (@var{method} @var{obuffer} @var{owindow} @var{thisbuffer}) @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 and 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}, 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{thisbuffer}. @c ??? Is this controlled by @var{method} ? 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 This fails to follow the manual's style conventions. 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. You can also set it manually, using the following code for displaying @var{buffer} in @var{window}: @example @group (display-buffer-record-window type window buffer) (set-window-buffer window buffer) (set-window-prev-buffers window nil) @end group @end example Setting the window history to @code{nil} ensures that a future call to @code{quit-window} can delete the window altogether. @end ignore @c ??? Is this fully correct? 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 frames. This function is called with one argument---a frame. The function specified here is called by @code{bury-buffer} (@pxref{Buffer List}) when the selected window is dedicated and shows the buffer to bury. It is also called by @code{quit-restore-window} (see above) when the frame of the window to quit has been specially created for displaying that window's buffer and the buffer is not killed. The default is to call @code{iconify-frame} (@pxref{Visibility of Frames}). Alternatively, you may specify either @code{delete-frame} (@pxref{Deleting Frames}) to remove the frame from its display, @code{make-frame-invisible} to make the frame invisible, @code{ignore} to leave the frame unchanged, or any other function that can take a frame as its sole argument. Note that the function specified by this option is called only if the specified frame contains just one live window and there is at least one other frame on the same terminal. For a particular frame, the value specified here may be overridden by that frame's @code{auto-hide-function} frame parameter (@pxref{Frame Interaction Parameters}). @end defopt -- Dr Richard Stallman (https://stallman.org) Chief GNUisance of the GNU Project (https://gnu.org) Founder, Free Software Foundation (https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org)