From: Sean Whitton <spwhitton@spwhitton.name>
Date: Fri, 2 May 2025 04:49:35 +0000 (+0800)
Subject: Move documentation of this-command buffer display condition entry
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=444c97036ac420cde3baf55acffadbed789ae412;p=emacs.git

Move documentation of this-command buffer display condition entry

* doc/lispref/buffers.texi (Buffer List): Document this-command
buffer display condition entry.
* doc/lispref/windows.texi (Choosing Window): Give an example of
using this-command buffer display condition entry in
display-buffer-alist.
(Buffer Display Action Alists):
* lisp/window.el (display-buffer): Delete documentation of
this-command buffer display condition entry from these locations
because it is not a buffer display action alist entry.
* lisp/subr.el (buffer-match-p): Update cross reference.

(cherry picked from commit d32ab06145a6055f5e39d348bddba72c3f705d75)
---

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index aad0499f51b..01aa620b828 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1006,6 +1006,13 @@ This is pertinent only when this function is called by
 satisfied if the action alist with which @code{display-buffer} was
 called includes @w{@code{(category . @var{expr})}} in the value of its
 @var{action} argument.  @xref{Buffer Display Action Alists}.
+@item this-command
+@vindex this-command@r{, a buffer display condition entry}
+This too is pertinent only when this function is called by
+@code{display-buffer} (@pxref{Buffer Display Action Alists}), and is
+satisfied when the command now being executed is equal to @var{expr}, or
+if @var{expr} is a list, when the command now being executed is a member
+of that list.
 @end table
 @item t
 Satisfied by any buffer.  A convenient alternative to @code{""} (empty
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 1c5a7264d3a..94ccf4a5f67 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3152,6 +3152,26 @@ as a symbol @code{comint}.  Then @code{display-buffer-alist} matches
 this category for all buffers displayed with the same category.
 This avoids the need to construct a complex regular expression
 that matches a buffer name.
+
+You can also match on the command now being executed.  This is useful
+when different commands display buffers with the same name, but you want
+different command's buffers to be displayed differently.  For example:
+
+@example
+@group
+(add-to-list 'display-buffer-alist
+             '((and "^\\*vc-diff\\*"
+                    (not (this-command . vc-root-diff)))
+	       nil
+	       (post-command-select-window . nil)))
+@end group
+@end example
+
+This means that windows displaying VC diffs, such as those generated by
+@kbd{C-x v =} (@code{vc-diff}, @pxref{Old Revisions,,, emacs, the Emacs
+Manual}) are not left selected, except for windows displaying buffers
+generated by @kbd{C-x v D} (@code{vc-root-diff}), which are left
+selected.
 @end defopt
 
 @defopt display-buffer-base-action
@@ -3914,14 +3934,6 @@ List, @code{buffer-match-p}}.  Thus, if a Lisp program uses a particular
 @var{symbol} as the category when calling @code{display-buffer}, users
 can customize how these buffers will be displayed by including such an
 entry in @code{display-buffer-alist}.
-
-@vindex this-command@r{, a buffer display action alist entry}
-@item this-command
-The value is a symbol naming a command or a list of command symbols.  It
-represents the condition which is satisfied if any of those commands are
-being executed.  You can use this in the condition part of
-@code{display-buffer-alist} entries to match buffers displayed during
-the execution of particular commands.
 @end table
 
 By convention, the entries @code{window-height}, @code{window-width}
diff --git a/lisp/subr.el b/lisp/subr.el
index 94c337559e5..62f395fc27d 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -7089,8 +7089,8 @@ CONDITION is either:
   * `this-command': the buffer matches if the command now being executed
     is `eq' to or a `memq' of the cons-cell's cdr.
     (This case is not useful when calling `buffer-match-p' directly, but
-    is needed to support the `this-command' buffer display action alist
-    entry.  See `display-buffer'.)
+    is needed to support the `this-command' buffer display condition
+    entry.  See Info node `(elisp)Choosing Window'.)
   * `not': the cadr is interpreted as a negation of a condition.
   * `and': the cdr is a list of recursive conditions, that all have
     to be met.
diff --git a/lisp/window.el b/lisp/window.el
index eccd6bb9d9a..052547de7df 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -8184,11 +8184,6 @@ Action alist entries are:
    `(category . symbol)' in its action argument, then you can match
    the displayed buffer by using the same category in the condition
    part of `display-buffer-alist' entries.
- `this-command' -- A symbol naming the command now being executed, or a
-  list of command symbols, to mean the condition that any of those
-  commands are being executed.
-  You can use this in the condition part of `display-buffer-alist'
-  entries to match buffers displayed by particular commands.
 
 The entries `window-height', `window-width', `window-size' and
 `preserve-size' are applied only when the window used for