From: Eric Abrahamsen <eric@ericabrahamsen.net>
To: emacs-devel@gnu.org
Subject: Re: Manual suggestions for quit-restore documentation
Date: Thu, 23 Mar 2017 12:49:12 -0700 [thread overview]
Message-ID: <8737e37ozr.fsf@ericabrahamsen.net> (raw)
In-Reply-To: 58BBE3DB.7000000@gmx.at
[-- Attachment #1: Type: text/plain, Size: 2075 bytes --]
martin rudalics <rudalics@gmx.at> 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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: windowmanual.diff --]
[-- Type: text/x-diff, Size: 7500 bytes --]
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
next prev parent reply other threads:[~2017-03-23 19:49 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-03-05 1:32 Manual suggestions for quit-restore documentation Eric Abrahamsen
2017-03-05 2:14 ` Drew Adams
2017-03-05 4:37 ` Eric Abrahamsen
2017-03-05 4:39 ` Eric Abrahamsen
2017-03-05 10:09 ` martin rudalics
2017-03-05 10:09 ` martin rudalics
2017-03-05 17:24 ` Eric Abrahamsen
2017-03-23 19:49 ` Eric Abrahamsen [this message]
2017-03-24 9:03 ` martin rudalics
2017-03-24 15:44 ` Eric Abrahamsen
2017-03-24 18:52 ` martin rudalics
2017-03-24 19:17 ` Eric Abrahamsen
2017-03-25 9:24 ` martin rudalics
2017-03-25 16:57 ` Eric Abrahamsen
2017-03-26 8:39 ` martin rudalics
2017-03-26 14:49 ` Eli Zaretskii
2017-03-26 15:33 ` Eric Abrahamsen
2017-03-26 16:27 ` Eli Zaretskii
2017-03-26 23:40 ` Eric Abrahamsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8737e37ozr.fsf@ericabrahamsen.net \
--to=eric@ericabrahamsen.net \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.