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 @defun buffer-match-p condition buffer-or-name &optional arg
This function checks if a buffer designated by @code{buffer-or-name} 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 @var{arg} is passed to the predicate function in @var{condition}. A
valid @var{condition} can be one of the following: valid @var{condition} can be one of the following:
@itemize @bullet{} @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 Satisfied if @emph{all} the conditions in @var{conds} satisfy
@code{buffer-match-p}, with the same buffer and @code{arg}. @code{buffer-match-p}, with the same buffer and @code{arg}.
@item derived-mode @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 @item major-mode
Satisfied if the buffer's major mode is equal to @var{expr}. Prefer 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 @end table
@item t @item t
Satisfied by any buffer. A convenient alternative to @code{""} (empty 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 @defun match-buffers condition &optional buffer-list arg
This function returns a list of all buffers that satisfy the 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{nil}. The argument @var{condition} is as defined in
@code{buffer-match-p} above. By default, all the buffers are @code{buffer-match-p} above. By default, all the buffers are
considered, but this can be restricted via the optional argument 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 @defopt display-buffer-alist
The value of this option is an alist mapping conditions to display The value of this option is an alist mapping conditions to display
actions. Each condition is passed to @code{buffer-match-p}, along actions. Each condition is passed to @code{buffer-match-p}
with the buffer name and the @var{action} argument passed to (@pxref{Buffer List}), along with the buffer name and the @var{action}
@code{display-buffer}. If it returns a non-@code{nil} value, then argument passed to @code{display-buffer}. If it returns a
@code{display-buffer} uses the corresponding display action to display non-@code{nil} value, then @code{display-buffer} uses the
the buffer. 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 @end defopt
@defopt display-buffer-base-action @defopt display-buffer-base-action