From 9af533dc751e5220a545ca7e15456992cbbfab98 Mon Sep 17 00:00:00 2001
From: Juri Linkov <juri@linkov.net>
Date: Tue, 2 Apr 2024 19:51:51 +0300
Subject: [PATCH] New condition/action entry 'category' for 'display-buffer'
 (bug#69983)

* doc/lispref/windows.texi (Choosing Window): Provide an example
of using '(category . comint)' in the condition of 'display-buffer-alist'
and in the action of 'display-buffer'.
(Buffer Display Action Alists): Add a new action alist entry 'category'.

* lisp/subr.el (buffer-match-p): Add a new condition 'category'.

* lisp/window.el (display-buffer): Document a new action alist entry
'category'.
---
 doc/lispref/windows.texi | 30 ++++++++++++++++++++++++++++++
 etc/NEWS                 |  8 ++++++++
 lisp/subr.el             |  5 +++++
 lisp/window.el           |  4 ++++
 4 files changed, 47 insertions(+)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index eef05d94fdb..d3d6b854461 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2638,6 +2638,29 @@ use @code{derived-mode} or @code{major-mode} as condition,
 @code{buffer-match-p} could fail to report a match if
 @code{display-buffer} is called before the major mode of the buffer is
 set.
+
+If the caller of @code{display-buffer} passes a category as a symbol
+in its @var{action} argument, then you can use the same category in
+@code{display-buffer-alist} to match buffers with different names,
+for example:
+
+@example
+@group
+(setopt
+ display-buffer-alist
+ (cons '((category . comint) (display-buffer-same-window))
+        display-buffer-alist))
+
+(display-buffer (get-buffer-create "*my-shell*")
+		'(nil (category . comint)))
+@end group
+@end example
+
+Regardless of the displayed buffer's name the caller defines a category
+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.
 @end defopt
 
 @defopt display-buffer-base-action
@@ -3354,6 +3377,13 @@ If the value is @code{nil}, the buffer selected by such functions as
 @code{pop-to-buffer} is deselected, and the window that was selected
 before calling this function will remain selected regardless of which
 windows were selected afterwards within this command.
+
+@vindex category@r{, a buffer display action alist entry}
+@item category
+If the caller of @code{display-buffer} passes an alist entry
+@code{(category . symbol)} in its @var{action} argument, then you can
+match the displayed buffer by using the same category in the condition
+part of @code{display-buffer-alist} entries.
 @end table
 
 By convention, the entries @code{window-height}, @code{window-width}
diff --git a/etc/NEWS b/etc/NEWS
index 4b0f148dc5d..47275db47e3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -291,6 +291,14 @@ right-aligned to is controlled by the new user option
 
 ** Windows
 
++++
+*** New action alist entry 'category' for 'display-buffer'.
+If the caller of 'display-buffer' passes '(category . symbol)'
+in its 'action' argument, you can match the displayed buffer
+by adding '(category . symbol)' to the condition part of
+'display-buffer-alist' entries.
+
++++
 *** New action alist entry 'post-command-select-window' for 'display-buffer'.
 It specifies whether the window of the displayed buffer should be
 selected or deselected at the end of executing the current command.
diff --git a/lisp/subr.el b/lisp/subr.el
index 50487e2c734..753c0144ca5 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -7475,6 +7475,9 @@ CONDITION is either:
   * `major-mode': the buffer matches if the buffer's major mode
     is eq to the cons-cell's cdr.  Prefer using `derived-mode'
     instead when both can work.
+  * `category': the buffer matches a category as a symbol if
+    the caller of `display-buffer' provides `(category . symbol)'
+    in its action argument.
   * `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.
@@ -7503,6 +7506,8 @@ CONDITION is either:
                               (push condition buffer-match-p--past-warnings))
                             (apply condition buffer-or-name
                                    (if args nil '(nil)))))))
+                      (`(category . ,category)
+                       (eq (alist-get 'category (cdar args)) category))
                       (`(major-mode . ,mode)
                        (eq
                         (buffer-local-value 'major-mode buffer)
diff --git a/lisp/window.el b/lisp/window.el
index df55a7ca673..46de1819c69 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7856,6 +7856,10 @@ Action alist entries are:
     window that was selected before calling this function will remain
     selected regardless of which windows were selected afterwards within
     this command.
+ `category' -- If the caller of `display-buffer' passes an alist entry
+   `(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.
 
 The entries `window-height', `window-width', `window-size' and
 `preserve-size' are applied only when the window used for