bug#52328: 27.2; [DOC] Paragraph about quit-restore-window

[Richard Stallman <rms@gnu.org>]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > It would be clearer to present the list using Lisp syntax:
  > > (@var{buffer} @var{window-start} @var{new-point})
  > > Then it can talk about these values with their names, which
  > > is clearer.

  > That is true.  But that's far from being the single or the main
  > problem of that description.

I had seen only at what was in the email I replied to.

  > I invite you to read the entire description of this function.

I just did that, and I agree it was very complex.  In addition,
it failed in many ways to follow Texinfo conventions and our
style conventions.

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.

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
screen, the user may decide to hide it and return to the previous
screen configuration.  We call that @dfn{quitting the window}.  The
way to do this is to call @code{quit-window}.

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?

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

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

@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?

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

@c ??? Is this controlled by @var{method} ?
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.


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



-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)