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

From: Eli Zaretskii <[email-masked]>
Date: Mon, 16 Jun 2025 12:52:00 +0300

> Date: Wed, 11 Jun 2025 16:30:04 -0700
> From: Chris Hibbert <[email-masked]>
> 
> I reported that "kill-buffer chooses a visible buffer as replacement" on
> the Emacs StackEchange.
> (https://emacs.stackexchange.com/questions/84630)
> 
> Someone responded, and once he understood my problem, pointed out that 
> switch-to-prev-buffer-skip provides the control I want.
> 
> I'm now suggesting that it would be helpful to document this better.

I think there's some confusion here, see below.

> For instance, the docs for kill-buffer
> (https://www.gnu.org/software/emacs/manual/html_node/emacs/Kill-Buffer.html),
> say that
>     "If you kill the current buffer, another buffer becomes current: one
>     that was current in the recent past but is  not displayed in any
>     window now."
> 
> That describes the behavior I want, but not the default, AFAICT.
> 
> I think the default value of switch-to-prev-buffer-skip is nil. The docs
> for switch-to-prev-buffer-skip say
>    If this variable is nil, ‘switch-to-prev-buffer’ may switch to
>    any buffer, including those already shown in other windows.

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.

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.

I'm adding Martin to this discussion, in the hope that he will have
more comments (and will correct me if I'm wrong).