bug#48493: 28.0.50; quit-window doesn't work

[Eli Zaretskii]

> From: pillule <pillule@riseup.net>
> Date: Tue, 08 Jun 2021 01:23:11 +0200
> Cc: pillule <pillule@riseup.net>, Sujith Manoharan <sujith.wall@gmail.com>,
>  48493@debbugs.gnu.org
> 
> > We have to document it in the Elisp manual.
> 
> Here another draft with the info manual changes:

Thanks.  Once again, I leave it to Martin and others to comment on
most of the essence of the patch, and provide here only few minor
nits:

> * doc/lispref/windows.texi
>   (Buffers and Windows): mention the exception of side windows and
> add a reference.
>   (Buffer Display Action Alists): explicit that
> `display-buffer-in-side-window' is dedicating to side by default.
>   (Dedicated Windows): add the case (4) and explicit its meaning,
> add a reference.
>   (Displaying Buffers in Side Windows): move the
> switch-to-(prev|next)-buffer paragraph into a new item to emphasize
> the special meaning of dedication for side windows.

Again, this log message is not formatted according to our rules.  It
should look like this:

* doc/lispref/windows.texi (Buffers and Windows): Mention the
exception of side windows and add a reference.
(Buffer Display Action Alists): Say explicitly that
'display-buffer-in-side-window' is dedicating to side by default.
(Dedicated Windows): Add case (4) and explain its meaning, add
a reference.
(Displaying Buffers in Side Windows): Move the paragraph about
'switch-to-(prev|next)-buffer' into a new item to emphasize the
special meaning of dedication for side windows.

Note that I also fixed the wording a bit, and that our conventions for
quoting in log entries is 'like this'.

>  The replacement buffer in each window is chosen via
> -@code{switch-to-prev-buffer} (@pxref{Window History}).  Any dedicated
> -window displaying @var{buffer-or-name} is deleted if possible
> -(@pxref{Dedicated Windows}).  If such a window is the only window on its
> -frame and there are other frames on the same terminal, the frame is
> -deleted as well.  If the dedicated window is the only window on the only
> -frame on its terminal, the buffer is replaced anyway.
> +@code{switch-to-prev-buffer} (@pxref{Window History}).  With the
> +exception of side windows, any dedicated window displaying
   ^^^^^^^^^^^^^^^^^^^^^^^^^
Here' it is quite important that the reader understands what are "side
windows", otherwise he/she will not understand the exception.
However, "side window" was not yet described in the manual by this
point, and its description is not in this section.  In these cases,
always include a cross-reference to where the term is described, like
this:

  With the exception of side windows (@pxref{Side Windows}), any ...

>     In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
> -handles case (2) by deleting the associated frame and case (3) by
> -showing another buffer in that frame's only window.  The function
> +handles case (2) by deleting the associated frame and case (3) and (4)
                                                         ^^^^
"cases", plural.

> +@item dedicated
> +The dedicated flag is not reserved to this function but have a
                                                      ^    ^^^^
A comma is missing before "but".  Also, please use "has" instead of
"have".

> +slightly different meaning for side windows.  They receive it upon
> +creation with the value @code{side}; it serves to prevent
> +@code{display-buffer} to uses these windows with others action
                         ^^^^^^^
"to use"

> +functions, and it persists across invocations of @code{quit-window},
> +@code{kill-buffer}, @code{previous-buffer} and @code{next-buffer}
> +(@pxref{note Window History}).  In particular, these commands will
           ^^^^^^^^^^^^^^^^^^^
No need for "note" here.