procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2024-11-21 12:28:26 +02:00
parent 4d80c4f485
commit 3eb3018682
3 changed files with 20 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/lispref/buffers.texi
View file

@ -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

13
doc/lispref/windows.texi
View file

@ -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}

7
lisp/subr.el
View file

@ -7447,9 +7447,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.