; Improve documentation of 'category' in display-buffer actions

* doc/lispref/windows.texi (Choosing Window)
(Buffer Display Action Alists): Add cross-references.
* doc/lispref/buffers.texi (Buffer List):

* lisp/subr.el (buffer-match-p): Improve documentation of
'category' condition.  (Bug#74361)

(cherry picked from commit 3eb3018682595208076fe7beea1175e123cf1966)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 5375eb641555b4cd62c8b6133a3fe7a47bad5699..5aa712e4247631c4986a7d15b72bfffa49896a49 100644 (file)
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1000,6 +1000,12 @@ Satisfied if the buffer's major mode is equal to @var{expr}.  Prefer
 using @code{derived-mode} instead, when both can work.  Note that this
 condition might fail to report a match if @code{buffer-match-p} is
 invoked before the major mode of the buffer has been established.
+@item category
+This is pertinent only when this function is called by
+@code{display-buffer} (@pxref{Buffer Display Action Alists}), and is
+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}.
 @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 0b8d7d3b76d1d4d9ff9242446827cf5867834dfd..595ac0c2fae863d8ddc4f463e0c50d128c5b8a20 100644 (file)
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2746,6 +2746,9 @@ for example:
 @end group
 @end example
 
+@noindent
+@xref{Buffer List, @code{buffer-match-p}}.
+
 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.
@@ -3495,9 +3498,13 @@ 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.
+@w{@code{(category . @var{symbol})}} in its @var{action} argument, then you
+can match the displayed buffer by using the same category symbol in the
+condition part of @code{display-buffer-alist} entries.  @xref{Buffer
+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}.
 @end table
 
 By convention, the entries @code{window-height}, @code{window-width}

diff --git a/lisp/subr.el b/lisp/subr.el
index 051faa862ca42b5bb7b2bd79875e2014b563233b..51ecf8a910da1b5ba43108bfbabff3618275a201 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -6960,9 +6960,10 @@ 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.
+  * `category': when this function is called from `display-buffer',
+    the buffer matches if the caller of `display-buffer' provides
+    `(category . SYMBOL)' in its ACTION argument, and SYMBOL is `eq'
+    to the cons-cell's cdr.
   * `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.