From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.devel Subject: Re: Manual suggestions for quit-restore documentation Date: Fri, 24 Mar 2017 12:17:45 -0700 Message-ID: <871stmfpra.fsf@ericabrahamsen.net> References: <87varoh5ka.fsf@ericabrahamsen.net> <58BBE3DB.7000000@gmx.at> <8737e37ozr.fsf@ericabrahamsen.net> <58D4E0F8.10500@gmx.at> <87mvca7k7h.fsf@ericabrahamsen.net> <58D56B0A.1070405@gmx.at> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1490383166 11057 195.159.176.226 (24 Mar 2017 19:19:26 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 24 Mar 2017 19:19:26 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Mar 24 20:19:18 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crUjz-00021O-Ra for ged-emacs-devel@m.gmane.org; Fri, 24 Mar 2017 20:19:16 +0100 Original-Received: from localhost ([::1]:34641 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crUk5-0002pX-Te for ged-emacs-devel@m.gmane.org; Fri, 24 Mar 2017 15:19:21 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36761) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crUjI-0002nW-6J for emacs-devel@gnu.org; Fri, 24 Mar 2017 15:18:33 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1crUjE-0001id-5R for emacs-devel@gnu.org; Fri, 24 Mar 2017 15:18:32 -0400 Original-Received: from [195.159.176.226] (port=33587 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1crUjD-0001iO-RN for emacs-devel@gnu.org; Fri, 24 Mar 2017 15:18:28 -0400 Original-Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1crUit-0003vl-QW for emacs-devel@gnu.org; Fri, 24 Mar 2017 20:18:07 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 215 Original-X-Complaints-To: usenet@blaine.gmane.org Cancel-Lock: sha1:vEOUchJy9zVYdF5Gv4F7ChhsuLA= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 195.159.176.226 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:213314 Archived-At: --=-=-= Content-Type: text/plain martin rudalics writes: >> Now I'm missing something -- I'm talking about (car quit-restore) -> >> 'other. Unless I'm really turned around, I don't see that getting checked. > > Right. What the code for 'other installs is currently checked by the > > ((and (listp (setq quad (nth 1 quit-restore))) > (buffer-live-p (car quad)) > (eq (nth 3 quit-restore) buffer)) > > condition. I didn't bother to check for 'other here since it's the only > remaining case. But if we ever want to add a new case in addition to > 'frame, 'window and 'other and that new case has the same structure as > 'other, we will have to check for 'other to discriminate the new case > from the 'other case. Hence, I recommend to use 'other even if it's > nowhere checked at the moment so code written from your recommendations > is prepared for future changes in this area. Aha! Now that's clear. I've added just a tiny bit to the windows parameter section, not really explaining but at least touching on it. I also deleted a couple of bits in an effort to be concise and clear. If this version looks okay to you I can install it. Eric --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Expand-manual-section-on-quitting-windows.patch >From 5ebfe3f23b07ccfb3985bc3462c6b6af686837d5 Mon Sep 17 00:00:00 2001 From: Eric Abrahamsen Date: Fri, 24 Mar 2017 12:10:06 -0700 Subject: [PATCH] Expand manual section on quitting windows * doc/lispref/windows.texi (Quitting Windows): Provide more information about the elements of the quit-restore window parameter, and how they affect the behavior of quit-restore-window. --- doc/lispref/windows.texi | 108 ++++++++++++++++++++++++++++------------------- 1 file changed, 65 insertions(+), 43 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index a4f8400170..125133cbb1 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2803,12 +2803,13 @@ Window History @section Window History @cindex window history -Each window remembers in a list the buffers it has previously displayed, -and the order in which these buffers were removed from it. This history -is used, for example, by @code{replace-buffer-in-windows} -(@pxref{Buffers and Windows}). The list is automatically maintained by -Emacs, but you can use the following functions to explicitly inspect or -alter it: +Each window remembers in a list the buffers it has previously +displayed, and the order in which these buffers were removed from it. +This history is used, for example, by @code{replace-buffer-in-windows} +(@pxref{Buffers and Windows}), and when quitting windows +(@pxref{Quitting Windows}). The list is automatically maintained by +Emacs, but you can use the following functions to explicitly inspect +or alter it: @defun window-prev-buffers &optional window This function returns a list specifying the previous contents of @@ -2994,33 +2995,35 @@ Quitting Windows @end deffn @defun quit-restore-window &optional window bury-or-kill -This function tries to restore the state of @var{window} that existed -before its buffer was displayed in it. The optional argument -@var{window} must be a live window and defaults to the selected one. +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 @code{quit-restore} window parameter (@pxref{Window +Parameters}), which is set to nil afterwards. + +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. -If @var{window} was created specially for displaying its buffer, this -function deletes @var{window} provided its frame contains at least one -other live window. 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. - -Otherwise, this function tries to redisplay the buffer previously shown -in @var{window}. It also tries to restore the window start -(@pxref{Window Start and End}) and point (@pxref{Window Point}) -positions of the previously shown buffer. If, in addition, +If the third element of the @code{quit-restore} parameter is a list of +buffer, window start (@pxref{Window Start and End}), and 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}. -The cases described so far require that the buffer shown in @var{window} -is still the buffer displayed by the last buffer display function for -this window. If another buffer has been shown in the meantime, or the -buffer previously shown no longer exists, this function calls -@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other -buffer instead. +Otherwise, if @var{window} was previously used for displaying other +buffers (@pxref{Window History}), the most recent buffer in that +history will be displayed. The optional argument @var{bury-or-kill} specifies how to deal with @var{window}'s buffer. The following values are handled: @@ -3048,9 +3051,24 @@ Quitting Windows This means to kill @var{window}'s buffer. @end table -@code{quit-restore-window} bases its decisions on information stored in -@var{window}'s @code{quit-restore} window parameter (@pxref{Window -Parameters}), and resets that parameter to @code{nil} after it's done. +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}: + +@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 nil ensures that a future call to +@code{quit-window} can delete the window altogether. + @end defun The following option specifies how to deal with a frame containing just @@ -4845,25 +4863,32 @@ Window Parameters (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} (@pxref{Quitting Windows}). It contains four elements: -The first element 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 -displayed the same buffer before; or @code{other}, the window showed -another buffer before. +The first element 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 this 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. +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 third element is the window selected at the time the parameter was -created. The function @code{quit-restore-window} tries to reselect that -window when it deletes the window passed to it as argument. +created. If @code{quit-restore-window} deletes the window passed to +it as argument, it then tries to reselect this window. 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. +See the description of @code{quit-restore-window} in @ref{Quitting +Windows} for details. + @item @code{window-side} @code{window-slot} These parameters are used for implementing side windows (@pxref{Side Windows}). @@ -4894,9 +4919,6 @@ Window Parameters versions of Emacs. @end table -The @code{window-atom} parameter is used for implementing atomic windows. - - @node Window Hooks @section Hooks for Window Scrolling and Changes @cindex hooks for window operations -- 2.12.1 --=-=-=--