; 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)

2 files changed, 16 insertions, 3 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 5375eb64155..5aa712e4247 100644
--- 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 f5963d984e9..c7e575b0e4f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2656,6 +2656,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.
@@ -3405,9 +3408,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}