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

From: Chris Hibbert <[email-masked]>
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
[email-masked]
Blog:   http://www.pancrit.org
http://mydruthers.com