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

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

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

I don’t understand the meaning of a paragraph in the Emacs Lisp
Reference Manual, chapter 28 Windows, section 28.16 Quitting Windows.

#+begin_quote
If the third element of the ‘quit-restore’ parameter is a list of
buffer, window start (*note Window Start and End), and point
(*note
Window Point), and that buffer is still live, the buffer will be
displayed, and start and point set accordingly. If, in addition,
WINDOW’s buffer was temporarily resized, this function will also try to
restore the original height of WINDOW.
#+end_quote

It seems to me that there could be an error in the presentation or in
the designation of the elements.

Is it the WINDOW parameter (second element of ‘quit-restore’) or is it
the window selected at the time the parameter was created (third element
of ‘quit-restore’)?
-- 
Best regards,
Kevin Vigouroux

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

[Richard Stallman]

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

  > If the third element of the ‘quit-restore’ parameter is a list of
  > buffer, window start (*note Window Start and End), and point
  > (*note
  > Window Point), 

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.

                   and that buffer is still live, the buffer will be
  > displayed, and start and point set accordingly.

It's bad to use passive voice; that is generally less clear because
of the missing subject, as well as more cluttered.

"Set accordingly" is hard work to interpret because it is not concrete.

This clarification will make it easier to clarify the questions
that Vigouroux is asking.


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

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 06 Dec 2021 23:15:19 -0500
> Cc: 52328@debbugs.gnu.org
> 
>   > If the third element of the ‘quit-restore’ parameter is a list of
>   > buffer, window start (*note Window Start and End), and point
>   > (*note
>   > Window Point), 
> 
> 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.

>                    and that buffer is still live, the buffer will be
>   > displayed, and start and point set accordingly.
> 
> It's bad to use passive voice; that is generally less clear because
> of the missing subject, as well as more cluttered.
> 
> "Set accordingly" is hard work to interpret because it is not concrete.

I invite you to read the entire description of this function.  It is
very complex and is IMO very hard to grasp.  I think it needs to be
completely rewritten, with the method of presenting the various
options rethought to be more clear.  One possibility is to describe
the options from the opposite POV: instead of saying "if the parameter
is this-and-that, the function will do some stuff", first describe a
job that the caller would want to do, with the rationale for that, and
then how to tell the function to do that job.

Other suggestions for clarifying that part will be most welcome.

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

[Richard Stallman]

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

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

[martin rudalics]

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

Thank you.  Note that at the time I coded 'quit-restore-window' I didn't
want to describe the 'quit-restore' parameter at all.  It is an internal
object that "others" shouldn't mess with, at least that's my conviction.

Then, in Bug#12158,

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=12158

Drew talked me into adding a description, something I still regret.

It took some time until Eric here

https://lists.gnu.org/archive/html/emacs-devel/2017-03/msg00085.html

explained his view of that parameter and added the text that is the
subject of the present report.

But I agree that if we do want to describe the 'quit-restore' parameter,
we should do better and your text certainly does that.

 > 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

... "to put a buffer", I suppose ...

 > screen, the user may decide to hide it and return to the previous
 > screen configuration.

There is no such thing as "the previous screen configuration".
Otherwise we could simply call 'set-window-configuration' here but that
could fail, in particular, when multiple frames are involved.  The basic
aim of 'quit-restore-window' was to avoid window configurations and
still intuitively DTRT when the user hits "q" in such a window.

 > We call that @dfn{quitting the window}.  The
 > way to do this is to call @code{quit-window}.

It's the "way to do this" only if the window used by 'display-buffer' is
selected at the time the user wants to get rid of it.  Otherwise, the
options you now do not mention should be used.

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

It is in windows.texi as

@vindex quit-restore@r{, a window parameter}

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

No.  We had some disagreement with Lars about this at the time he added
that hook.  I think that adding 'quit-window-hook' was a bad idea.

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

Note that you have to finish the description of 'quit-window' before
describing 'quit-restore-window'.  The arguments you describe below
(like 'bury-or-kill') belong to 'quit-window'.

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

... takes ...

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

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

No.  For example, a dedicated window is deleted without consulting the
'quit-restore' parameter in the first place.  Handling dedicated windows
was always a mystery for me, so the prior description might be far from
accurate.  One idea of the 'quit-restore' parameter was to get rid of
dedicated windows but that was an obstacle I never succeeded to handle.

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

.. is the buffer ...

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

... this-buffer ...

 > @c ??? Is this controlled by @var{method} ?

Only in the sense that "method" did not provide anything useful.

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

Probably.  Maybe Eric finds a solution.

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

I think that saying "to do the right thing" is a way to work around
answering that question.  For me 'frame-auto-hide-function' was a
misguided attempt to work around a request by Drew to not iconify a
frame after quitting its only window (IIRC).  Since it deals with
dedicated windows I cannot say much about it.

 > 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

martin

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

[Richard Stallman]

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

  > Thank you.  Note that at the time I coded 'quit-restore-window' I didn't
  > want to describe the 'quit-restore' parameter at all.  It is an internal
  > object that "others" shouldn't mess with, at least that's my conviction.

The description is clearer and simpler than it was before.
Do you still think it would be better to delete it?

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

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

[martin rudalics]

 > The description is clearer and simpler than it was before.
 > Do you still think it would be better to delete it?

I still think that it would have been better, if a detailed description
of the 'quit-restore' parameter had never made it into the manual.  But
once a description is in the manual, you cannot get rid of it any more.

Can you please try to look into the issues I raised in my reply?

Thank you, martin

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

[Richard Stallman]

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

  > I still think that it would have been better, if a detailed description
  > of the 'quit-restore' parameter had never made it into the manual.  But
  > once a description is in the manual, you cannot get rid of it any more.

I don't see what would prevent that -- if it is the best thing to do.

The manual could say that the `quit-restore' window parameter records information about how `display-buffer' set up that window, for use by `quit-window'.

Do others agree this would be better?


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

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

[Drew Adams]

I can't speak to what the manual should or shouldn't
say about `quit-restore'.  But since my name was
mentioned I'll just say that I never knowingly or
intentionally use `quit-window' interactively.  I go
out of my way to avoid any use of the `quit-restore'
window parameter.

I replace Emacs's default `quit-window' key bindings,
at least those in libraries I load, with the command
below.

It's close to what `quit-window' used to do, before
Emacs adopted `quit-restore-window'.

(In its doc string, you'll see mention of the option
that Martin mentioned, `frame-auto-hide-function',
which he offered as a way around the imposition by
Emacs of iconifying a window when quitting it or
burying its buffer.) 

(when (fboundp 'quit-restore-window)

  (defun quit-window-delete (&optional kill window)
    "Quit WINDOW, deleting it, and bury its buffer.
WINDOW must be a live window and defaults to the selected one.
With prefix argument KILL non-nil, kill the buffer instead of
burying it.

This is similar to the version of `quit-window' that Emacs had before
the introduction of `quit-restore-window'.  It ignores the information
stored in WINDOW's `quit-restore' window parameter.

It deletes the WINDOW more often, rather than switching to another
buffer in it.  If WINDOW is alone in its frame then the frame is
deleted or iconified, according to option `frame-auto-hide-function'."
    (interactive "P")
    (set-window-parameter
      window 'quit-restore `(frame frame nil ,(current-buffer)))
    (quit-restore-window window (if kill 'kill 'bury)))

  )

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

[Richard Stallman]

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

I'll leave it to others to think about whether to change the behavior
of quit-window.

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

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

[Richard Stallman]

[[[ 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's the "way to do this" only if the window used by 'display-buffer' is
  > selected at the time the user wants to get rid of it.  Otherwise, the
  > options you now do not mention should be used.

I don't understand what that refers to.

  > Note that you have to finish the description of 'quit-window' before
  > describing 'quit-restore-window'.  The arguments you describe below
  > (like 'bury-or-kill') belong to 'quit-window'.

I did not delete any arguments from the description of `quit-window'.
And it does not seem to have an argument called BURY-OR-KILL.
What, specifically, is missing?

  > No.  For example, a dedicated window is deleted without consulting the
  > 'quit-restore' parameter in the first place.  Handling dedicated windows
  > was always a mystery for me, so the prior description might be far from
  > accurate.  One idea of the 'quit-restore' parameter was to get rid of
  > dedicated windows but that was an obstacle I never succeeded to handle.

I don't know what to say about that case, so I will leave the comment
with the question.

  >  > @c ??? Is this fully correct?

  > I think that saying "to do the right thing" is a way to work around
  > answering that question.  For me 'frame-auto-hide-function' was a
  > misguided attempt to work around a request by Drew to not iconify a
  > frame after quitting its only window (IIRC).  Since it deals with
  > dedicated windows I cannot say much about it.

I don't understand that comment.  The question is not about whether
this feature is useful, or whether it ought to be changed.  It's
whether the text in the manual is correct or not.  Can anyone tell?

It is possible to consider changing this featurelet, or deleting it,
but I'm not proposing either of those.  Just working on the manual.

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

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

[martin rudalics]

 > I did not delete any arguments from the description of `quit-window'.
 > And it does not seem to have an argument called BURY-OR-KILL.
 > What, specifically, is missing?

Sorry.  It seems that I have been mixing up manual texts on master in
some intractable way.  I currently cannot use master in the usual way
because it immediately hogs my old CPU, probably due to Bug#52298.

So I suppose that your modifications are correct, considerably improve
the original text and I've been all wrong with my comments.

 > It is possible to consider changing this featurelet, or deleting it,
 > but I'm not proposing either of those.  Just working on the manual.

Hopefully, Eli will decide what's better.  Thanks a lot for your efforts.

martin

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

[Richard Stallman]

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

Would someone please install my changes to windows.texi?

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

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 11 Dec 2021 23:00:33 -0500
> Cc: eric@ericabrahamsen.net, ke.vigouroux@laposte.net, 52328@debbugs.gnu.org
> 
> Would someone please install my changes to windows.texi?

It's on my todo, and I will get to it, eventually.

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

[Eli Zaretskii]

> Resent-From: Eli Zaretskii <eliz@gnu.org>
> Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
> Resent-CC: bug-gnu-emacs@gnu.org
> Resent-Sender: help-debbugs@gnu.org
> Date: Sun, 12 Dec 2021 09:02:47 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: eric@ericabrahamsen.net, 52328@debbugs.gnu.org, ke.vigouroux@laposte.net
> 
> > From: Richard Stallman <rms@gnu.org>
> > Date: Sat, 11 Dec 2021 23:00:33 -0500
> > Cc: eric@ericabrahamsen.net, ke.vigouroux@laposte.net, 52328@debbugs.gnu.org
> > 
> > Would someone please install my changes to windows.texi?
> 
> It's on my todo, and I will get to it, eventually.

Now done.

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

[Eli Zaretskii]

> Date: Mon, 06 Dec 2021 12:46:58 +0100
> From:  Kevin Vigouroux via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> If the third element of the ‘quit-restore’ parameter is a list of
> buffer, window start (*note Window Start and End), and point
> (*note
> Window Point), and that buffer is still live, the buffer will be
> displayed, and start and point set accordingly. If, in addition,
> WINDOW’s buffer was temporarily resized, this function will also try to
> restore the original height of WINDOW.
> #+end_quote
> 
> It seems to me that there could be an error in the presentation or in
> the designation of the elements.
> 
> Is it the WINDOW parameter (second element of ‘quit-restore’) or is it
> the window selected at the time the parameter was created (third element
> of ‘quit-restore’)?

Neither, AFAIU.  It's the WINDOW argument of quit-restore-window
function, i.e. the window the function is quitting.  The upper-case
WINDOW signals that it refers to an argument of a function, not to
some symbol by that name.

I do agree that the description of the function is very hard to
understand, due to the multitude of possible formats of the
quit-restore parameter and the meaning of its elements.

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

[martin rudalics]

 > If the third element of the ‘quit-restore’ parameter is a list of
 > buffer, window start (*note Window Start and End), and point
 > (*note
 > Window Point), and that buffer is still live, the buffer will be
 > displayed, and start and point set accordingly. If, in addition,
 > WINDOW’s buffer was temporarily resized, this function will also try to
 > restore the original height of WINDOW.
 > #+end_quote
 >
 > It seems to me that there could be an error in the presentation or in
 > the designation of the elements.
 >
 > Is it the WINDOW parameter (second element of ‘quit-restore’) or is it
 > the window selected at the time the parameter was created (third element
 > of ‘quit-restore’)?

The manual is wrong.  It is the _second_ element of the 'quit-restore'
parameter and not the third.

Thanks, martin