From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#52328: 27.2; [DOC] Paragraph about quit-restore-window Date: Wed, 8 Dec 2021 12:02:21 +0100 Message-ID: <8fdf37fa-38f5-cf83-c3bb-e04c4eed8dfb@gmx.at> References: <87tufm0xcd.fsf@laposte.net> <83mtlcxnwi.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="12337"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Eric Abrahamsen , ke.vigouroux@laposte.net, 52328@debbugs.gnu.org To: rms@gnu.org, Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Dec 08 12:03:16 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 1muujC-0002vs-7v for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 08 Dec 2021 12:03:14 +0100 Original-Received: from localhost ([::1]:36502 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1muujA-0000T5-S3 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 08 Dec 2021 06:03:12 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:38116) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muuj1-0000Qi-Gk for bug-gnu-emacs@gnu.org; Wed, 08 Dec 2021 06:03:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56288) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1muuj0-0008Op-85 for bug-gnu-emacs@gnu.org; Wed, 08 Dec 2021 06:03:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1muuj0-0005iA-5b for bug-gnu-emacs@gnu.org; Wed, 08 Dec 2021 06:03:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 Dec 2021 11:03: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.163896136421931 (code B ref 52328); Wed, 08 Dec 2021 11:03:02 +0000 Original-Received: (at 52328) by debbugs.gnu.org; 8 Dec 2021 11:02:44 +0000 Original-Received: from localhost ([127.0.0.1]:39601 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muuii-0005he-0U for submit@debbugs.gnu.org; Wed, 08 Dec 2021 06:02:44 -0500 Original-Received: from mout.gmx.net ([212.227.17.22]:33505) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muuig-0005hP-BT for 52328@debbugs.gnu.org; Wed, 08 Dec 2021 06:02:43 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1638961345; bh=uQyrpKxFBqvluuq2eWVFiyjULNX1DtECHzmShGZGVt0=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=VComrjgjMJkIpSUH+WjTQfrt5rHeCbug7UZ8/ito6hVrthpoY76Z6Cf5oQCri0JWX varJoAIxByJU9pqFDKL4JyLxWF+4EL86emfToyNWoib4ipAh78gAqvSgTPyV3Fi5GV GTjPuF3a9Xip0mtm0/Bcvwb+icqATWEHRbqcChH8= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [192.168.1.101] ([212.95.5.228]) by mail.gmx.net (mrgmx104 [212.227.17.168]) with ESMTPSA (Nemesis) id 1McYCb-1mPAOz48VB-00d09E; Wed, 08 Dec 2021 12:02:25 +0100 In-Reply-To: Content-Language: en-US X-Provags-ID: V03:K1:ziyLJTBr8bKnXj/RwLYwGE5EBbkvI0v6ZecL5eQ5gxk+5THFHIN wD48BdNCbvXoRj+31U0SA41++6y8W4eZ0s8MczNLCT3c1W6QDBmSaaUVAZihGah0XssKjaR WE25dmq2uSE2Picn3jhWgObytrypG+ieqUmzdkog5vQOd+wyXMJHGN1+zVNu85THd/OMUyv 7pKwWgbkUTvHHQbOC/1Ww== X-UI-Out-Filterresults: notjunk:1;V03:K0:GOZDtQIes4c=:C26TAsBiMOgdArrY2DWxf0 411Zm0w04VC+OWy2/FjIKMhvHXzfa1RtgsiUIUbffFAOLumdc2EoHJnmR1rK72a+JZgecdVc3 rrcPKVSLnL6PIe6tAXACng35nt+POTqqZ/vPXglNpSKKH/yUAkDm4COyv7qZzCnYRzWrOAmmY 3nA62YCoIf27xqNZglXfAJEkIMrXyUJYKIicl11kDKc6rWFOEWbkZ3mJmmmkEKpT4HcDpxoye WAHB6HQsf8wKNXZ5fV/+YORCn/UWsTjT0LnCnirFgc3HY4J7ru9JaKXCQJjqSKclfAGdeTBJF 58+GQ1XJbiAOzNAJpwh9IG54DmO3WJclSCrTpcBaIL6t7qM7BCO29FA3P9nN/RnuFJPBkqwX4 kINdOGsz4Sx8IUxgNEA0vOjWVns/kHeqdXz1b6a2V2xTktvYRrX6/iFIB2xhInSv2Rh2TLpkq oQyu9aWY3K3GTDSkM52rEk3exJ4z+GCp1u448lQPc3Uq+/R12NdNyGeU1ImSvQ5HrgUK2gX8s VF0FyUiH6uJ9m21BTY32y+Q8nb4+Hc5gZSmzSZeAkEgmJHCGYNrl2+ry7ssIKUYm630vEIqfc GMBsWJufybmjSz9mCKF2ZfUBzgizKL6nM+vNBRICZwRbk4P6spcrXMJtmpveqvS/F4Z1D0s44 I+nfR775RnhzVbKn+Ki/LnJusbscOD2QRlDzYFWcPBxNI1wQHYh1tvkdJg0wcRlEMMfGTUuqM ILYvNHp04F/PlCBHP280Ls6FPx08rfI9CIpyo7XFn/iQI6ASUX7wfDpybJ7L5ahIN8MHFufS 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:221918 Archived-At: > 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. Thank you. Note that at the time I coded 'quit-restore-window' I didn't want to describe the 'quit-restore' parameter at all. It is an internal object that "others" shouldn't mess with, at least that's my conviction. Then, in Bug#12158, https://debbugs.gnu.org/cgi/bugreport.cgi?bug=12158 Drew talked me into adding a description, something I still regret. It took some time until Eric here https://lists.gnu.org/archive/html/emacs-devel/2017-03/msg00085.html explained his view of that parameter and added the text that is the subject of the present report. But I agree that if we do want to describe the 'quit-restore' parameter, we should do better and your text certainly does that. > 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 ... "to put a buffer", I suppose ... > screen, the user may decide to hide it and return to the previous > screen configuration. There is no such thing as "the previous screen configuration". Otherwise we could simply call 'set-window-configuration' here but that could fail, in particular, when multiple frames are involved. The basic aim of 'quit-restore-window' was to avoid window configurations and still intuitively DTRT when the user hits "q" in such a window. > We call that @dfn{quitting the window}. The > way to do this is to call @code{quit-window}. It's the "way to do this" only if the window used by 'display-buffer' is selected at the time the user wants to get rid of it. Otherwise, the options you now do not mention should be used. > 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? It is in windows.texi as @vindex quit-restore@r{, a window parameter} > @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? No. We had some disagreement with Lars about this at the time he added that hook. I think that adding 'quit-window-hook' was a bad idea. > @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. Note that you have to finish the description of 'quit-window' before describing 'quit-restore-window'. The arguments you describe below (like 'bury-or-kill') belong to 'quit-window'. > @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 ... takes ... > @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. ... buffer 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? No. For example, a dedicated window is deleted without consulting the 'quit-restore' parameter in the first place. Handling dedicated windows was always a mystery for me, so the prior description might be far from accurate. One idea of the 'quit-restore' parameter was to get rid of dedicated windows but that was an obstacle I never succeeded to handle. > @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 .. is the buffer ... > 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}. ... this-buffer ... > @c ??? Is this controlled by @var{method} ? Only in the sense that "method" did not provide anything useful. > 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. Probably. Maybe Eric finds a solution. > 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? I think that saying "to do the right thing" is a way to work around answering that question. For me 'frame-auto-hide-function' was a misguided attempt to work around a request by Drew to not iconify a frame after quitting its only window (IIRC). Since it deals with dedicated windows I cannot say much about it. > 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 martin