Manual suggestions for quit-restore documentation

Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

[-- Attachment #1: Type: text/plain, Size: 708 bytes --]

As mentioned in a thread in emacs.help, I've got some suggestions for
the parts of the Elisp manual that touch on the quit-restore window
parameter, and its behaviors.

I've attached a diff with my edits; if/when some version of this is
eventually approved I can do a proper commit.

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".

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: windowsdoc.diff --]
[-- Type: text/x-patch, Size: 3320 bytes --]

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index affa28c920..504a74dfd1 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
@@ -2998,15 +2999,17 @@ Quitting Windows
 before its buffer was displayed in it.  The optional argument
 @var{window} must be a live window and defaults to the selected one.
 
-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.
+If @var{window} was previously used for displaying other buffers
+(@pxref{Window History}), the most recent buffer in that history will
+be displayed.  If it has no history, this function deletes
+@var{window} altogether, 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
@@ -4857,8 +4860,9 @@ Window Parameters
 window when 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.
+this parameter.  @code{quit-restore-window} deletes the specified
+window only if it still shows that buffer, and it has no history of
+previously-displayed buffers.
 
 @item @code{window-side} @code{window-slot}
 These parameters are used for implementing side windows (@pxref{Side

RE: Manual suggestions for quit-restore documentation

[Drew Adams]

> As mentioned in a thread in emacs.help, I've got some suggestions for
> the parts of the Elisp manual that touch on the quit-restore window
> parameter, and its behaviors.
> 
> I've attached a diff with my edits; if/when some version of this is
> eventually approved I can do a proper commit.
> 
> 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".

Good initiative! Thanks. I agree that more is needed, but I
too don't understand it well enough.

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

Drew Adams <drew.adams@oracle.com> writes:

>> As mentioned in a thread in emacs.help, I've got some suggestions for
>> the parts of the Elisp manual that touch on the quit-restore window
>> parameter, and its behaviors.
>> 
>> I've attached a diff with my edits; if/when some version of this is
>> eventually approved I can do a proper commit.
>> 
>> 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".
>
> Good initiative! Thanks. I agree that more is needed, but I
> too don't understand it well enough.

There's some pretty deep grass, here. I only just came across "Side
Windows", which is pretty interesting -- that could conceivably do away
with Gnus' whole homemade window configuration setup.

If Marcin ends up patching `display-buffer-record-window' to un-set
buffer history when appropriate, I think it would also be worth
mentioning that function in the docs, as the go-to function for setting
the quit-restore parameter.

E

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>>> As mentioned in a thread in emacs.help, I've got some suggestions for
>>> the parts of the Elisp manual that touch on the quit-restore window
>>> parameter, and its behaviors.
>>> 
>>> I've attached a diff with my edits; if/when some version of this is
>>> eventually approved I can do a proper commit.
>>> 
>>> 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".
>>
>> Good initiative! Thanks. I agree that more is needed, but I
>> too don't understand it well enough.
>
> There's some pretty deep grass, here. I only just came across "Side
> Windows", which is pretty interesting -- that could conceivably do away
> with Gnus' whole homemade window configuration setup.
>
> If Marcin ends up patching `display-buffer-record-window' to un-set

*Martin, sorry.

> buffer history when appropriate, I think it would also be worth
> mentioning that function in the docs, as the go-to function for setting
> the quit-restore parameter.
>
> E

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 > If Marcin ends up patching `display-buffer-record-window' to un-set
 > buffer history when appropriate, I think it would also be worth
 > mentioning that function in the docs, as the go-to function for setting
 > the quit-restore parameter.

I'm afraid it won't work as I already noticed earlier: If we just use

    (set-window-prev-buffers window nil)

    (set-window-buffer window buffer)

then with ‘display-buffer-pop-up-window’ the ‘set-window-buffer’ will
record the buffer shown in that window due to ‘split-window’ as the
previous buffer and quitting that window will not delete it but try to
show the buffer put there by ‘split-window’ instead.

So the canonical order to do things is

    (display-buffer-record-window type window buffer)

    (set-window-buffer window buffer)

    (set-window-prev-buffers window nil)

So when you document this, then please mention that if someone wants to
use ‘display-buffer-record-window’ in her code, then in the `window'
case she manually has to clear the list of previous buffers as well
(it's not strictly necessary in the `frame' case but it won't harm
either).

martin

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 > 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".

Trying to recall.

      The first element is one of the symbols `window', meaning that the
      window has been specially created by `display-buffer'; `frame', a
      separate frame has been created; `same', the window has displayed
      the same buffer before; or `other', the window showed another
      buffer before.

If the first element is `window', we usually want to delete that window
but have to cater for a few special cases: For example, the window might
have become the only window on its frame since it was created in which
case we cannot simply delete the frame.  Or, the user might have
switched to another buffer in it in which case calling ‘quit-window’
probably should do just nothing.

If the first element is `frame', the situation is similar to the former
just that we now have to cater for the case that the window is no more
the only one on its frame in which case the frame should probably not be
deleted.

`same' is more tricky: We want to do certain things only if a window
always displayed the same buffer.  For example, automatic resizing of
the *help* window (via ‘temp-buffer-resize-mode’) should happen only if
that window was created specially for *help* and was subsequently reused
for *help* only.  If the *help* window was showing another buffer before
or in between, no such resizing should occur.

`other' signals more or less that the user has restricted the way new
pop-up windows/frames can be created and the (typically second on the
frame) window was (and probably will be) used for showing another
buffer.  In this case we usually do not delete the window, even if after
a sequence of `quit-window' calls the first buffer ever shown in that
window reappeared (we do not remember that much).

      The second element is either one of the symbols `window' or
      `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.

The values `window' and `frame' for the second element are redundant
IIRC.  Maybe we could as well leave them nil.  Iff the second element is
a list, it tells how to show the "other" buffer that was shown in that
window before when the window is quit.  That's important when that other
buffer appears in yet another window at the time of quitting - we may
want to restore the old `window-point' and `window-start' position, if
possible.

martin

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

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".
>
> Trying to recall.

Oof, no wonder documentation is currently slim. Thanks for all these
explanations; I'll take a little time and look through the code and make
sure I actually understand this before trying to document it. As per
your other message, I'll also add a bit about how to do it "manually".

Thanks again,
Eric

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

[-- 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

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 > 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 :)

Isn't that via

(defun quit-restore-window (&optional window bury-or-kill)
            ...
	   ;; Delete WINDOW if possible.
	   (window--delete window nil (eq bury-or-kill 'kill)))

and

(defun window--delete (&optional window dedicated-only kill)
           ...
	  (cond
	   (kill
	    (delete-frame frame))

or what am I missing?

 > 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.

I suppose it's used here

(defun quit-restore-window (&optional window bury-or-kill)
      ...
      ((and (listp (setq quad (nth 1 quit-restore)))
	   (buffer-live-p (car quad))

and it's essential when the window was used for showing an "other"
buffer.

 > +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.

Correct IMHO.  So what is still unclear about `bury-or-kill'?

 > +possible to set it manually, using the following code when displaying
 > +``buffer'' in ``window'':

Both `buffer' and `window' are arguments so I'd use var{} here.

 > +The final use of @code{set-window-prev-buffers} ensures that a future
 > +call to @code{quit-window} will delete the window altogether.
 > +

I'd prefer something like "Setting @code{set-window-prev-buffers} _to
nil_ ensures that a future call to @code{quit-window} _can_ delete the
window altogether."

 > +window showed another buffer before. The 'frame and 'window elements

I think we use `frame' and `window' instead of 'frame and 'window.

 > +re-uses the window to display the buffer.

Would "reuses" be bad English?

Thanks for working on this, martin

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> 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 :)
>
> Isn't that via
>
> (defun quit-restore-window (&optional window bury-or-kill)
>            ...
> 	   ;; Delete WINDOW if possible.
> 	   (window--delete window nil (eq bury-or-kill 'kill)))
>
> and
>
> (defun window--delete (&optional window dedicated-only kill)
>           ...
> 	  (cond
> 	   (kill
> 	    (delete-frame frame))
>
> or what am I missing?

Ah, of course -- I even looked in there, but it didn't click.

>> 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.
>
> I suppose it's used here
>
> (defun quit-restore-window (&optional window bury-or-kill)
>      ...
>      ((and (listp (setq quad (nth 1 quit-restore)))
> 	   (buffer-live-p (car quad))
>
> and it's essential when the window was used for showing an "other"
> buffer.

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.

>> +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.
>
> Correct IMHO.  So what is still unclear about `bury-or-kill'?

I think it's fine, I was just confused. I might tweak the wording
slightly.

>> +possible to set it manually, using the following code when displaying
>> +``buffer'' in ``window'':
>
> Both `buffer' and `window' are arguments so I'd use var{} here.
>
>> +The final use of @code{set-window-prev-buffers} ensures that a future
>> +call to @code{quit-window} will delete the window altogether.
>> +
>
> I'd prefer something like "Setting @code{set-window-prev-buffers} _to
> nil_ ensures that a future call to @code{quit-window} _can_ delete the
> window altogether."

That's still a bit off, as it sounds like we're setting the function
name to nil. How about:

Setting the window history to nil ensures that a future call to
@code{quit-window} can delete the window altogether.

Is that clear enough, do you think?

>> +window showed another buffer before. The 'frame and 'window elements
>
> I think we use `frame' and `window' instead of 'frame and 'window.

Good, thanks for this and the @var{} tip, I don't have much experience
writing texinfo.

>> +re-uses the window to display the buffer.
>
> Would "reuses" be bad English?

No, they're both acceptable spellings, "reuses" is fine.

Let me know what you think about 'other, and I'll do a proper commit.

Eric

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 > 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.

 > That's still a bit off, as it sounds like we're setting the function
 > name to nil. How about:
 >
 > Setting the window history to nil ensures that a future call to
 > @code{quit-window} can delete the window altogether.

Perfect!

 >>> +re-uses the window to display the buffer.
 >>
 >> Would "reuses" be bad English?
 >
 > No, they're both acceptable spellings, "reuses" is fine.
 >
 > Let me know what you think about 'other, and I'll do a proper commit.

Let me know if my remark above was not clear enough.

Thanks again for working on this, martin

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

[-- Attachment #1: Type: text/plain, Size: 1148 bytes --]

martin rudalics <rudalics@gmx.at> 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Expand-manual-section-on-quitting-windows.patch --]
[-- Type: text/x-patch, Size: 8288 bytes --]

From 5ebfe3f23b07ccfb3985bc3462c6b6af686837d5 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 > 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.

Looks good now.  There is one missing space

+window showed another buffer before. @code{frame} and @code{window}
                                      ^
				     here.

So please install whenever you like.

Thanks, martin

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> 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.
>
> Looks good now.  There is one missing space
>
> +window showed another buffer before. @code{frame} and @code{window}
>                                      ^
> 				     here.

Good catch.

> So please install whenever you like.

Done! Thanks for your guidance.

Eric

Re: Manual suggestions for quit-restore documentation

[martin rudalics]

 >> So please install whenever you like.
 >
 > Done! Thanks for your guidance.

Fine!  Thanks for your efforts.

martin

Re: Manual suggestions for quit-restore documentation

[Eli Zaretskii]

> Date: Sun, 26 Mar 2017 10:39:24 +0200
> From: martin rudalics <rudalics@gmx.at>
> 
>  >> So please install whenever you like.
>  >
>  > Done! Thanks for your guidance.
> 
> Fine!  Thanks for your efforts.

Ehm... if the docs changes describe the functionality existing also on
the emacs-25 branch, the changes should be pushed to the branch, not
to master.

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sun, 26 Mar 2017 10:39:24 +0200
>> From: martin rudalics <rudalics@gmx.at>
>> 
>>  >> So please install whenever you like.
>>  >
>>  > Done! Thanks for your guidance.
>> 
>> Fine!  Thanks for your efforts.
>
> Ehm... if the docs changes describe the functionality existing also on
> the emacs-25 branch, the changes should be pushed to the branch, not
> to master.

Grr, sorry. I should have asked to be sure. Should it be cherry-picked
over, or how is this handled?

Re: Manual suggestions for quit-restore documentation

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Sun, 26 Mar 2017 08:33:43 -0700
> 
> > Ehm... if the docs changes describe the functionality existing also on
> > the emacs-25 branch, the changes should be pushed to the branch, not
> > to master.
> 
> Grr, sorry. I should have asked to be sure. Should it be cherry-picked
> over, or how is this handled?

Yes, please cherry-pick to the emacs-25 branch.

Thanks.

Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Date: Sun, 26 Mar 2017 08:33:43 -0700
>> 
>> > Ehm... if the docs changes describe the functionality existing also on
>> > the emacs-25 branch, the changes should be pushed to the branch, not
>> > to master.
>> 
>> Grr, sorry. I should have asked to be sure. Should it be cherry-picked
>> over, or how is this handled?
>
> Yes, please cherry-pick to the emacs-25 branch.

Done.