bug#69983: Use category for display-buffer-alist

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 69983@debbugs.gnu.org
> From: Juri Linkov <juri@linkov.net>
> Date: Thu, 28 Mar 2024 09:47:37 +0200
> 
> diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
> index eef05d94fdb..54e563eeb58 100644
> --- a/doc/lispref/windows.texi
> +++ b/doc/lispref/windows.texi
> @@ -2638,6 +2638,23 @@ Choosing Window
>  @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.
> +
> +When the caller of @code{display-buffer} passes a category as a symbol

Please use "If", not "When" in such cases.  "When" has a meaning of
time, which is not what you mean here.

> +in its @var{action} argument, then @code{display-buffer-alist} can use it
> +to match a whole category of buffers with different buffer 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

I failed to understand from the description and the example the
meaning of 'category' in this case.  Specifically, I think the
description should tell more about the interpretation of the symbol in
(category . SYMBOL).  The example gives 'comint' as the category
symbol and says this matches "a whole category of buffers", but
doesn't explain enough to understand which buffers will match this
category and which won't.  IOW, the meaning of 'comint' as "category
of buffers" is not sufficiently explained.

> --- a/lisp/subr.el
> +++ b/lisp/subr.el
> @@ -7476,6 +7474,8 @@ buffer-match-p
>    * `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 if the caller of `display-buffer'
> +    provided `(category . symbol)' in its ACTION argument.

Same here.  (And "symbol" should be "SYMBOL", upper-case, I think.

Thanks.