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: Thu, 23 Mar 2017 12:49:12 -0700 Message-ID: <8737e37ozr.fsf@ericabrahamsen.net> References: <87varoh5ka.fsf@ericabrahamsen.net> <58BBE3DB.7000000@gmx.at> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1490298585 7460 195.159.176.226 (23 Mar 2017 19:49:45 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 23 Mar 2017 19:49:45 +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 Thu Mar 23 20:49:41 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 1cr8jl-0000ii-A6 for ged-emacs-devel@m.gmane.org; Thu, 23 Mar 2017 20:49:34 +0100 Original-Received: from localhost ([::1]:58268 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cr8jr-0003lS-A9 for ged-emacs-devel@m.gmane.org; Thu, 23 Mar 2017 15:49:39 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58827) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cr8jk-0003lM-EM for emacs-devel@gnu.org; Thu, 23 Mar 2017 15:49:34 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cr8jh-00065b-B4 for emacs-devel@gnu.org; Thu, 23 Mar 2017 15:49:32 -0400 Original-Received: from [195.159.176.226] (port=38513 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cr8jg-00065P-W1 for emacs-devel@gnu.org; Thu, 23 Mar 2017 15:49:29 -0400 Original-Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1cr8jU-0007Yo-RG for emacs-devel@gnu.org; Thu, 23 Mar 2017 20:49:16 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 214 Original-X-Complaints-To: usenet@blaine.gmane.org Cancel-Lock: sha1:GJvdQEUCjRgt1eUXYcN3ZZ/epr8= 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:213276 Archived-At: --=-=-= Content-Type: text/plain martin rudalics writes: >> I've attached a diff with my edits; if/when some version of this is >> eventually approved I can do a proper commit. > > Thanks. Please install. > >> I didn't add anything in the Window Parameters section about the first >> two elements of the quit-restore parameter, simply because I don't >> understand them well enough. I still think something should be said >> there about how they influence quit behavior, though -- this is the >> first place that people will look to find out how this works, and the >> current docs are very clear about "what", but beg the question of "why". Okay, I got distracted for a while there, but here's another version. I reworked the `quit-restore-window' section, and now it makes sense to me, at any rate. I'm fairly uncertain about this paragraph: 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. The window will never be deleted, however, if it is the only one in its frame. 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. I just don't see how/where the `bury-or-kill' parameter affects the handling of the frame, I think it only affects the buffer. But I may have "fixed" it until it doesn't make sense :) I added a line about 'same as the first element of `quit-restore', but it might be wrong. I didn't add anything new about the 'other symbol. I see it getting set in `display-buffer-record-window', but I don't see that it ever gets used. Hope this is nearly there, Eric --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=windowmanual.diff diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index a4f8400170..1577ac2f30 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,27 +2995,37 @@ 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. The window will never be deleted, +however, if it is the only one in its frame. 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 the 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. + 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 @@ -3048,9 +3059,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 when displaying +``buffer'' in ``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 + +The final use of @code{set-window-prev-buffers} ensures that a future +call to @code{quit-window} will delete the window altogether. + @end defun The following option specifies how to deal with a frame containing just @@ -4845,25 +4871,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. The 'frame and 'window elements +affect how the window is quit, while 'same affects the redisplay of +buffers 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} +re-uses 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. @code{quit-restore-window} tries to reselect that window if +it deletes the window passed to it as argument. 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 +4927,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 --=-=-=--