From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 21 Jul 2025 12:35:36 +0000 (+0300)
Subject: Improve documentation of 'quit-window'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b20a8244bdb648ccc8950050bc09dadefa8621da;p=emacs.git

Improve documentation of 'quit-window'

* lisp/window.el (quit-window): Mention 'quit-window-kill-buffer'.
(quit-window): Doc fix.

* doc/lispref/windows.texi (Quitting Windows):
* etc/NEWS: Improve documentation of 'quit-window-kill-buffer'.

(cherry picked from commit 5485bda52399a23d95ab593dcb748975ee0654d0)
---

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 94ccf4a5f67..87dfaad7fda 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -5014,10 +5014,11 @@ To enable @code{quit-window} to do the right thing,
 window's @code{quit-restore} parameter (@pxref{Window Parameters}).
 
 @deffn Command quit-window &optional kill window
-This command quits @var{window} and buries its buffer.  The argument
-@var{window} must be a live window and defaults to the selected one.
-With prefix argument @var{kill} non-@code{nil}, it kills the buffer
-instead of burying it.
+This command quits @var{window} and buries its buffer.  (It could also
+kill the buffer, subject to @code{quit-window-kill-buffer}, see below.)
+The argument @var{window} must be a live window and defaults to the
+selected one.  With prefix argument @var{kill} non-@code{nil}, it kills
+the buffer instead of burying it.
 
 @vindex quit-window-hook
 The function @code{quit-window} first runs @code{quit-window-hook}.
@@ -5025,18 +5026,21 @@ Then it calls the function @code{quit-restore-window}, described below,
 which does the hard work.
 @end deffn
 
-The following option tells @code{quit-window} whether it should
-preferably kill or bury @var{window}'s buffer.
+The following option tells @code{quit-window} whether it should kill or
+bury @var{window}'s buffer when the @var{kill} argument is @code{nil}.
 
 @defopt quit-window-kill-buffer
-If this is @code{nil} and @var{kill} is @code{nil}, @code{quit-window}
-will bury @var{window}'s buffer.  If this is @code{t},
-@code{quit-window} will try to kill @var{window}'s buffer.  Otherwise,
-this should be a list of major modes.  @code{quit-window} will kill the
-buffer of @var{window} regardless of the value of @var{kill} if that
-buffer's major mode is either a member of this list or is derived from a
-member of this list.  In any other case, @code{quit-window} will kill
-the buffer only if @var{kill} is non-@code{nil} and bury it otherwise.
+This variable controls whether @code{quit-window} kills the buffer of
+its @var{window} argument.  If the value is @code{nil} (the default)
+@code{quit-window} will kill @var{window}'s buffer only if the
+@var{kill} argument is non-@code{nil}.  If this is @code{t},
+@code{quit-window} will try to kill @var{window}'s buffer regardless of
+the value of the @var{kill} argument.  Otherwise, this should be a list
+of major modes; @code{quit-window} will kill the buffer of @var{window}
+regardless of the value of @var{kill} if that buffer's major mode is
+either a member of this list or is derived from a member of this list.
+In any other case, @code{quit-window} will kill the buffer only if
+@var{kill} is non-@code{nil} and bury it otherwise.
 @end defopt
 
 You can get more control by calling @code{quit-restore-window} instead
diff --git a/lisp/window.el b/lisp/window.el
index 304ec058aa3..d14ca0d0a43 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -5459,15 +5459,16 @@ elsewhere.  This value is used by `quit-windows-on'."
       (bury-buffer-internal buffer)))))
 
 (defcustom quit-window-kill-buffer nil
-  "Non-nil means `quit-window' will try to kill WINDOW's buffer.
-If this is nil and the KILL argument is nil, `quit-window' will bury
-WINDOW's buffer.  If this is t, `quit-window' will always try to kill
-WINDOW's buffer.  Otherwise, this should be a list of major modes.
-`quit-window' will kill the buffer of its WINDOW argument regardless of
-the value of KILL if that buffer's major mode is either a member of this
-list or is derived from a member of this list.  In any other case,
-`quit-window' will kill the buffer only if KILL is non-nil and bury it
-otherwise."
+  "Non-nil means `quit-window' will try to kill buffer of WINDOW it quits.
+If this variable is nil (the default), `quit-window' will bury WINDOW's
+buffer if the KILL argument is nil and kill it otherwise.
+If this is t, `quit-window' will try to kill WINDOW's buffer regardless
+of the value of KILL.
+If this is a list of major modes, `quit-window' will kill the WINDOW's
+buffer regardless of the value of KILL if that buffer's major mode is
+either a member of this list or is derived from a member of this list.
+For any other value, `quit-window' will kill the buffer only if KILL is
+non-nil and bury it otherwise."
   :type '(choice (boolean :tag "All major modes")
 		 (repeat (symbol :tag "Major mode")))
   :version "31.1"
@@ -5477,7 +5478,9 @@ otherwise."
   "Quit WINDOW and bury its buffer.
 WINDOW must be a live window and defaults to the selected one.
 With prefix argument KILL non-nil, kill the buffer instead of
-burying it.
+burying it.  If `quit-window-kill-buffer' is non-nil, perhaps
+kill the buffer even if KILL is nil; see the doc string of
+that variable for the details.
 
 This calls the function `quit-restore-window' to delete WINDOW or
 show some other buffer in it.  See Info node `(elisp) Quitting