Subject: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find

From: Drew Adams <[email-masked]>
Date: Mon, 16 Jun 2025 17:21:26 +0000

>  > There are two related, but different behaviors here, which both happen
>  > when the current buffer is killed:
>  >
>  >    . which buffer becomes the current one, and
>  >    . which buffer replaces the current buffer in its window
>  >
>  > The manual's documentation of the behavior of kill-buffer which you
>  > quote talks about the former, whereas switch-to-prev-buffer-skip
>  > affects the latter.
> 
> Indeed.  By virtue of the fact that the command loop makes the selected
> window's buffer current, a user gets the impression that these are one
> and the same.
> 
>  > So I don't see a problem in the documentation, and AFAIU the
>  > correction you suggested for the manual is incorrect, because it
>  > wrongly conflates these two subtly different behaviors.
> 
> We could say
> 
>    If you kill the current buffer, Emacs makes another buffer current and
>    either shows another buffer in every window showing the old current
>    buffer or deletes such a window.  If you are not satisfied with that
>    behavior, try customizing the options `kill-buffer-quit-windows'
>    and/or `switch-to-prev-buffer-skip'.  In either case, the command loop
>    will eventually make the now selected window's buffer current.
> 
> instead.

+1 to this or similar.
___

And please mention it in (elisp) `Window History'.  In Emacs
30.1, that doc says nothing about the relation between option
`switch-to-prev-buffer-skip' and `kill-buffer'.  That's
probably because there's no `kill-buffer-quit-windows' in 30.1,
but for 30.2+ it should be mentioned, I think.

Doesn't the nil default value of `switch-to-prev-buffer-skip'
also mean a change in the default behavior for `kill-buffer'?
If so, one can wonder why the longstanding _default_ behavior
was changed.  Please mention this change in NEWS.

In addition to those two "related, but different behaviors"
being coupled in the way you say, there's the coupling of
previous-buffer behaviors _in general_ with `kill-buffer's
own use of such a behavior.

In the past this coupling wasn't a problem, but now it seems
there can be a difference between what a user might want for
`kill-buffer' and what they might want for other uses of
previous-buffer handling - no?  How can a user tell Emacs 
what window-handling behavior to use wrt `kill-buffer', and
distinguish that from the behavior wanted for other
previous-buffer uses?