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

; Improve documentation of 'buffer-match-p'

Browse source 
* doc/lispref/buffers.texi (Buffer List):
* doc/lispref/windows.texi (Choosing Window): Add caveats for
calling 'buffer-match-p' too early, when CONDITION is
'derived-mode' or 'major-mode'.  (Bug#68081)
This commit is contained in:
Eli Zaretskii 2024-01-06 11:15:31 +02:00
parent dc9d02f8a0
commit 2a861124e8
2 changed files with 18 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/buffers.texi
View file

@ -959,7 +959,7 @@ infinite recursion.
@defun buffer-match-p condition buffer-or-name &optional arg
This function checks if a buffer designated by @code{buffer-or-name}
satisfies the specified @code{condition}. Optional third argument
satisfies the specified @var{condition}. Optional third argument
@var{arg} is passed to the predicate function in @var{condition}. A
valid @var{condition} can be one of the following:
@itemize @bullet{}
@ -987,10 +987,15 @@ Satisfied if @emph{any} condition in @var{conds} satisfies
Satisfied if @emph{all} the conditions in @var{conds} satisfy
@code{buffer-match-p}, with the same buffer and @code{arg}.
@item derived-mode
Satisfied if the buffer's major mode derives from @var{expr}.
Satisfied if the buffer's major mode derives from @var{expr}. 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 major-mode
Satisfied if the buffer's major mode is equal to @var{expr}. Prefer
using @code{derived-mode} instead, when both can work.
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.
@end table
@item t
Satisfied by any buffer. A convenient alternative to @code{""} (empty
@ -1000,7 +1005,7 @@ string) or @code{(and)} (empty conjunction).
@defun match-buffers condition &optional buffer-list arg
This function returns a list of all buffers that satisfy the
@code{condition}. If no buffers match, the function returns
@var{condition}. If no buffers match, the function returns
@code{nil}. The argument @var{condition} is as defined in
@code{buffer-match-p} above. By default, all the buffers are
considered, but this can be restricted via the optional argument

14
doc/lispref/windows.texi
View file

@ -2629,11 +2629,15 @@ default value is an empty display action, i.e., @w{@code{(nil . nil)}}.
@defopt display-buffer-alist
The value of this option is an alist mapping conditions to display
actions. Each condition is passed to @code{buffer-match-p}, along
with the buffer name and the @var{action} argument passed to
@code{display-buffer}. If it returns a non-@code{nil} value, then
@code{display-buffer} uses the corresponding display action to display
the buffer.
actions. Each condition is passed to @code{buffer-match-p}
(@pxref{Buffer List}), along with the buffer name and the @var{action}
argument passed to @code{display-buffer}. If it returns a
non-@code{nil} value, then @code{display-buffer} uses the
corresponding display action to display the buffer. Caveat: if you
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.
@end defopt
@defopt display-buffer-base-action