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

Previous Next

To reply to this bug, email your comments to 78785 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Chris Hibbert <hibbert <at> mydruthers.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Wed, 11 Jun 2025 16:30:04 -0700

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

If the default value of switch-to-prev-buffer-skip is changed to
'visible', the doc for kill-buffer would be correct. Alternatively, we
could replace the line I quoted from kill-buffer to say

   "If you kill the current buffer, another buffer becomes current: the
   default chooses an arbitrary buffer. To specify a different strategy,
   set the variable switch-to-prev-buffer-skip to a non-nil value.
   'visible' tells it to skip buffers that are visible.


Chris


In GNU Emacs 29.3 (build 1, aarch64-apple-darwin21.6.0, NS
 appkit-2113.60 Version 12.6.6 (Build 21G646)) of 2024-03-24 built on
 armbob.lan
Windowing system distributor 'Apple', version 10.3.2575
System Description:  macOS 15.5

Configured using:
 'configure --with-ns '--enable-locallisppath=/Library/Application
 Support/Emacs/${version}/site-lisp:/Library/Application
 Support/Emacs/site-lisp' --with-modules 'CFLAGS=-DFD_SETSIZE=10000
 -DDARWIN_UNLIMITED_SELECT' --with-x-toolkit=no'

Configured features:
ACL GLIB GMP GNUTLS JPEG JSON LIBXML2 MODULES NOTIFY KQUEUE NS PDUMPER
PNG RSVG SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Text

Minor modes in effect:
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  shell-dirtrack-mode: t
  desktop-save-mode: t
  server-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  line-number-mode: t
  visual-line-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  abbrev-mode: t

Load-path shadows:
/Users/chris/.emacs.d/elpa/transient-0.8.8/transient hides 
/Applications/Emacs.app/Contents/Resources/lisp/transient

Features:
(shadow sort mail-extr emacsbug completion mode-local shortdoc
magit-extras expand magit-bookmark bookmark filecache xref project
tabify cus-start flyspell apropos ispell warnings sh-script rx
executable help-fns radix-tree cl-print debug backtrace find-func rect
compare-w files-x grep compile display-line-numbers dabbrev doc-view
jka-compr image-mode exif misearch multi-isearch dired-aux vc-hg vc-bzr
vc-src vc-sccs vc-svn vc-cvs vc-rcs log-view vc bug-reference
magit-ediff ediff ediff-merg ediff-mult ediff-wind ediff-diff ediff-help
ediff-init ediff-util face-remap lisp-mnt magit-submodule magit-blame
magit-stash magit-reflog magit-bisect magit-push magit-pull magit-fetch
magit-clone magit-remote magit-commit magit-sequence magit-notes
magit-worktree magit-tag magit-merge magit-branch magit-reset
magit-files magit-refs magit-status magit magit-repos magit-apply
magit-wip magit-log which-func magit-diff smerge-mode diff git-commit
log-edit message sendmail dired dired-loaddefs rfc822 mml mml-sec epa
derived epg rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse
rfc2231 rfc2047 rfc2045 ietf-drums mailabbrev gmm-utils mailheader
pcvs-util add-log magit-core magit-autorevert magit-margin
magit-transient magit-process with-editor shell pcomplete comint
ansi-osc ring ansi-color magit-mode transient edmacro kmacro benchmark
magit-git magit-base magit-section format-spec cursor-sensor crm llama
compat compat-30 cl-extra help-mode yank-media mhtml-mode css-mode smie
eww xdg url-queue thingatpt shr pixel-fill kinsoku url-file svg xml puny
mm-url gnus nnheader gnus-util text-property-search mail-utils range
mm-util mail-prsvr color sgml-mode facemenu dom autorevert filenotify
vc-git diff-mode easy-mmode vc-dispatcher js c-ts-common treesit imenu
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs time-date desktop frameset server cus-edit pp cus-load
icons wid-edit finder-inf magit-autoloads pcase magit-section-autoloads
llama-autoloads transient-autoloads with-editor-autoloads info
compat-autoloads package browse-url url url-proxy url-privacy url-expand
url-methods url-history url-cookie generate-lisp-file url-domsuf
url-util mailcap url-handlers url-parse auth-source cl-seq eieio
eieio-core cl-macs password-cache json subr-x map byte-opt gv bytecomp
byte-compile url-vars cl-loaddefs cl-lib rmc iso-transl tooltip cconv
eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/ns-win ns-win ucs-normalize mule-util
term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads kqueue cocoa ns multi-tty make-network-process emacs)

Memory information:
((conses 16 373297 130580)
 (symbols 48 26162 0)
 (strings 32 103677 10744)
 (string-bytes 1 3319413)
 (vectors 16 63608)
 (vector-slots 8 1610226 242811)
 (floats 8 399 511)
 (intervals 56 5463 6415)
 (buffers 984 45))

-- 
Currently reading: The Coming Wave, Mustafa Suleyman; Infinity
    Hold 3, Barry B. Longyear; Cancelled: The Shape of Things to
    Come, by Danny King; The Algebraist, Iain Banks; 1638: The
    Sovereign States, Eric Flint, et. al

Chris Hibbert
hibbert <at> mydruthers.com
Blog:   http://www.pancrit.org
http://mydruthers.com

Message #8 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Chris Hibbert <hibbert <at> mydruthers.com>, martin rudalics <rudalics <at> gmx.at>
Cc: 78785 <at> debbugs.gnu.org
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Mon, 16 Jun 2025 12:52:00 +0300

> Date: Wed, 11 Jun 2025 16:30:04 -0700
> From: Chris Hibbert <hibbert <at> mydruthers.com>
> 
> 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).

Message #11 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Eli Zaretskii <eliz <at> gnu.org>, Chris Hibbert <hibbert <at> mydruthers.com>
Cc: 78785 <at> debbugs.gnu.org
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Mon, 16 Jun 2025 17:50:15 +0200

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

martin

Message #14 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Stéphane Marks <shipmints <at> gmail.com>
To: martin rudalics <rudalics <at> gmx.at>
Cc: Chris Hibbert <hibbert <at> mydruthers.com>, Eli Zaretskii <eliz <at> gnu.org>,
 78785 <at> debbugs.gnu.org
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Mon, 16 Jun 2025 12:35:30 -0400

[Message part 1 (text/plain, inline)]

On Mon, Jun 16, 2025 at 11:51 AM martin rudalics via Bug reports for GNU
Emacs, the Swiss army knife of text editors <bug-gnu-emacs <at> gnu.org> wrote:

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

If you're a tab-bar user, there's also this user option
`tab-bar-select-restore-windows` to take a look at.

[Message part 2 (text/html, inline)]

Message #17 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Chris Hibbert <hibbert <at> mydruthers.com>
To: Eli Zaretskii <eliz <at> gnu.org>, martin rudalics <rudalics <at> gmx.at>
Cc: 78785 <at> debbugs.gnu.org, shipmints <at> gmail.com
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Mon, 16 Jun 2025 09:43:25 -0700

On 6/16/25 2:52 AM, Eli Zaretskii wrote:
> 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.

I'm confused by this explanation. When kill-buffer starts re-using 
visible buffers, the statement "another buffer becomes current: one that 
was current in the recent past but is not displayed in any window now" 
doesn't seem true in any sense. When switch-to-prev-buffer-skip is nil, 
even if there are other non-displayed buffers available, it doesn't 
choose any of them, instead displaying one that's already visible.

One plausible interpretation of "one that was current in the recent 
past" is that there's a cache somewhere, and it gets exhausted. If that 
were the case, I'd hope for access to or control of the size of the 
cache. If there's no cache, then it should always be able to find the 
non-visible buffers to use before the visible ones.

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

Martin's explanation is definitely an improvement on that.

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

On 6/16/25 8:50 AM, martin rudalics wrote:
> 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 selectedwindow's buffer
>   current.

I couldn't find any documentation of kill-buffer-quit-windows either on 
the gnu site, within emacs (apropos, describe variables, ^h-d, searching 
within Info), or by asking google.

Chris
-- 
Market[s] sets wages as a function of the marginal productivity of
the worker. Therefore technology – which raises productivity –
drives wages up, not down.
     --  https://a16z.com/the-techno-optimist-manifesto/

Chris Hibbert
hibbert <at> mydruthers.com
Blog:   http://www.pancrit.org
http://mydruthers.com

Message #20 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>, Chris
 Hibbert <hibbert <at> mydruthers.com>
Cc: "78785 <at> debbugs.gnu.org" <78785 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#78785: 29.3; docs: switch-to-prev-buffer-skip is
 hard to find
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?

Message #23 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Chris Hibbert <hibbert <at> mydruthers.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 78785 <at> debbugs.gnu.org, shipmints <at> gmail.com
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Tue, 17 Jun 2025 12:57:46 +0200

> I'm confused by this explanation. When kill-buffer starts re-using
> visible buffers, the statement "another buffer becomes current: one
> that was current in the recent past but is not displayed in any window
> now" doesn't seem true in any sense. When switch-to-prev-buffer-skip
> is nil, even if there are other non-displayed buffers available, it
> doesn't choose any of them, instead displaying one that's already
> visible.

You're conflating two actions performed by 'kill-buffer':

- It first calls 'replace-buffer-in-windows' via

  replace_buffer_in_windows (buffer);

  to make sure that BUFFER is no more shown in any window.

- It then checks if BUFFER is the current buffer and if so makes another
  buffer current via

  if (b == current_buffer)
    {
      tem = Fother_buffer (buffer, Qnil, Qnil);
      Fset_buffer (tem);
      if (b == current_buffer)
	return Qnil;
    }

  If you look at the specification of 'other-buffer', you will see that
  the VISIBLE-OK argument is nil here, so replacing the current buffer
  does not choose a visible buffer unless all other buffers are visible
  and the doc is correct just as Eli said.

Eventually, the command loop will make the buffer of the selected window
current and that buffer may be indeed shown in any other window already.

You have to look into the documentations of 'replace-buffer-in-windows'
and 'switch-to-prev-buffer' to find out under which circumstances these
may show an already visible buffer.  The main reason is to accommodate
the following user behavior:

- The user types C-x 2 to look at two different portions of one and the
  same buffer.

- The users invokes a command to display a *Help* or *Info* buffer in
  one of these windows.

- The users kills the *Help* or *Info* buffer.

In this situation, our user expects that the original state before
invoking the help or info command gets restored thus showing the same
buffer in two windows.

As a rule, 'switch-to-prev-buffer' switches to a buffer previously shown
in that window.  If, in your case, this unwantedly shows the same buffer
in two windows, then the explanation usually is that the window that
showed the killed buffer did show the buffer it switched to before.

> One plausible interpretation of "one that was current in the recent
> past" is that there's a cache somewhere, and it gets exhausted. If
> that were the case, I'd hope for access to or control of the size of
> the cache. If there's no cache, then it should always be able to find
> the non-visible buffers to use before the visible ones.

I can only repeat myself: Replacing the current buffer is not involved
in this scenario.  It's the selected window's buffer that gets replaced
and later made current by the command loop.

martin

Message #26 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, Eli Zaretskii <eliz <at> gnu.org>,
 Chris Hibbert <hibbert <at> mydruthers.com>
Cc: "78785 <at> debbugs.gnu.org" <78785 <at> debbugs.gnu.org>
Subject: Re: [External] : bug#78785: 29.3; docs: switch-to-prev-buffer-skip is
 hard to find
Date: Tue, 17 Jun 2025 12:58:43 +0200

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

'kill-buffer' calls 'replace-buffer-in-windows' which is documented in
the Elisp manual as

     This function calls ‘replace-buffer-in-windows’ for cleaning up all
     windows currently displaying the buffer to be killed.

'replace-buffer-in-windows' calls 'switch-to-prev-buffer' documented as

     The replacement buffer in each window is usually chosen via
     ‘switch-to-prev-buffer’ (*note Window History::).

'switch-to-prev-buffer' consults 'switch-to-prev-buffer-skip' documented
as

     The option ‘switch-to-prev-buffer-skip’ described below can be used
     to inhibit switching to certain buffers, for example, to those
     already shown in another window.

> That's
> probably because there's no `kill-buffer-quit-windows' in 30.1,
> but for 30.2+ it should be mentioned, I think.

'kill-buffer-quit-windows' will be in Emacs 31.  You will have to read
its documentation there.

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

I don't remember the sequence of events leading to the present behavior.
I'll let Eli decide if mentioning any change in NEWS is needed.

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

The coupling of 'switch-to-prev-buffer', 'quit-window' and 'kill-buffer'
has indeed become tighter because users wanted that.  You will have to
consult the discussions here and on emacs-devel for further details.

martin

Message #29 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Chris Hibbert <hibbert <at> mydruthers.com>
Cc: rudalics <at> gmx.at, 78785 <at> debbugs.gnu.org, shipmints <at> gmail.com
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Tue, 17 Jun 2025 14:02:51 +0300

> Date: Mon, 16 Jun 2025 09:43:25 -0700
> Cc: 78785 <at> debbugs.gnu.org, shipmints <at> gmail.com
> From: Chris Hibbert <hibbert <at> mydruthers.com>
> 
> On 6/16/25 2:52 AM, Eli Zaretskii wrote:
> > 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.
> 
> I'm confused by this explanation.

Confused in what sense?  In the sense that you cannot easily correlate
that to what you see in a running Emacs session?  That's because the
two processes I described happen one after the other, and users only
see the results of both of them.

My point is that there are two processes, and each one is controlled
by a different set of options and rules.  Conflating them into one, as
you tried to do, will only muddy the waters and make prediction of
what happens harder.

> When kill-buffer starts re-using 
> visible buffers, the statement "another buffer becomes current: one that 
> was current in the recent past but is not displayed in any window now" 
> doesn't seem true in any sense.

It does, you just might not see it under some circumstances.

> When switch-to-prev-buffer-skip is nil, 
> even if there are other non-displayed buffers available, it doesn't 
> choose any of them, instead displaying one that's already visible.

That's because Emacs always forces the buffer of the selected window
to become the current buffer, when it (Emacs) displays the results of
killing the current buffer.  But before that happens, some other
buffer might become the current one.

> One plausible interpretation of "one that was current in the recent 
> past" is that there's a cache somewhere, and it gets exhausted. If that 
> were the case, I'd hope for access to or control of the size of the 
> cache. If there's no cache, then it should always be able to find the 
> non-visible buffers to use before the visible ones.

I don't think this is what happens in your case.

> > 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.
> 
> Martin's explanation is definitely an improvement on that.

I think it again conflates the two processes.  We need to describe
them separately, and in a way that clarifies that they are separate.
So if we decide to amend the manual, I'll try to come up with text
which emphasizes that aspect more clearly.

Meanwhile, I don't think I understand what was your practical problem
with kill-buffer.  Can you tell what you tried to achieve and what
information was missing in the documentation which would have helped
you do what you wanted?  Because this discussion started without a
clear description of the original problem (and the StackExchange
discussion doesn't clarify that, either).

Thanks.

Message #32 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: hibbert <at> mydruthers.com, rudalics <at> gmx.at, 78785 <at> debbugs.gnu.org
Subject: Re: [External] : bug#78785: 29.3; docs: switch-to-prev-buffer-skip is
 hard to find
Date: Tue, 17 Jun 2025 14:06:01 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "78785 <at> debbugs.gnu.org" <78785 <at> debbugs.gnu.org>
> Date: Mon, 16 Jun 2025 17:21:26 +0000
> 
> 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.

The kill-buffer-quit-windows option exists only starting from
Emacs 31.1.

Message #35 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "hibbert <at> mydruthers.com" <hibbert <at> mydruthers.com>,
 "rudalics <at> gmx.at" <rudalics <at> gmx.at>,
 "78785 <at> debbugs.gnu.org" <78785 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#78785: 29.3; docs: switch-to-prev-buffer-skip is
 hard to find
Date: Tue, 17 Jun 2025 15:33:38 +0000

> > 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.
> 
> The kill-buffer-quit-windows option exists only starting from
> Emacs 31.1.

OK (I was thinking it would be in 30.2).

Message #38 received at 78785 <at> debbugs.gnu.org (full text, mbox):

From: Chris Hibbert <hibbert <at> mydruthers.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rudalics <at> gmx.at, 78785 <at> debbugs.gnu.org, shipmints <at> gmail.com
Subject: Re: bug#78785: 29.3; docs: switch-to-prev-buffer-skip is hard to find
Date: Tue, 17 Jun 2025 15:47:02 -0700

On 6/17/25 4:02 AM, Eli Zaretskii wrote:
> 
> Meanwhile, I don't think I understand what was your practical problem
> with kill-buffer.  Can you tell what you tried to achieve and what
> information was missing in the documentation which would have helped
> you do what you wanted?  Because this discussion started without a
> clear description of the original problem (and the StackExchange
> discussion doesn't clarify that, either).
> 
> Thanks.

I'll reframe my original problem that led to the report. Meanwhile, I'll 
concede that I don't get how the two phase process that chooses a window 
and then a buffer to display (or is it vice-versa?) works, but I don't 
need to, I think.

A thing that often happens to me is that I'm working on editing several 
files in multiple windows in a single frame to get some task done. At 
some point, I decide that I'm done, and I want to sequentially kill all 
the buffers, checking that they were saved (and I wasn't in the middle 
of something in each) as I go.

Long ago, it was the case that each time I deleted one buffer, it would 
be replaced by a different relatively recently visited buffer, which I 
could take a look at, and then delete or edit, and then continue with 
clean-up. More recently, the behavior changed, so that after I had 
killed a few buffers, it would replace the killed buffer with another 
that was already visible. This meant I would kill a buffer, then ask 
emacs to give me a different recently-visited buffer, and then look at 
that one. If I have 3 or 4 windows open, when I kill the current one, 
showing in more than one window, both buffers are replaced in their 
windows by the same buffer.

Now with (setq switch-to-prev-buffer-skip 'visible), I get the behavior 
I want. When I kill a buffer, I get to see a different recent buffer. If 
I kill a buffer that is displayed in more than one window, each window 
gets is replaced by a different recently visited buffer.

I'm satisfied with this behavior, but I started this long discussion 
because I thought the manual on kill-buffer said that it did what I 
wanted in the default case. I don't think it does.

https://www.gnu.org/software/emacs/manual/html_node/emacs/Kill-Buffer.html#:~:text=C%2Dx%20k%20(%20kill%2Dbuffer%20),displayed%20in%20any%20window%20now.

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

Chris
-- 
Competition is virtually indistinguishable from anticompetitive
behavior. Every firm strives to undercut its rivals, to put its
rivals out of business, ... or to steal its rivals' customers.
   --- Geoffrey Manne and Justin Hurwitz, ICLE

Chris Hibbert
hibbert <at> mydruthers.com
Blog:   http://www.pancrit.org
http://mydruthers.com

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.