Re: master c3ab8f1: Improve buffer-match-p documentation

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> diff --git a/etc/NEWS b/etc/NEWS
> index 7d474ac..14d970f 100644
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -1492,6 +1492,13 @@ them towards or away from each other.
>  This hook is run before 'x-popup-menu' is about to display a
>  deck-of-cards menu on screen.
> 
> +** New function 'buffer-match-p'
> +Check if a buffer matches a condition, specified using a DSL.

A "DSL"? what's that?  We don't have that acronym anywhere else in
Emacs, AFAICS.  Please make that entry more self-explanatory.

Thanks.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> diff --git a/etc/NEWS b/etc/NEWS
>> index 7d474ac..14d970f 100644
>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -1492,6 +1492,13 @@ them towards or away from each other.
>>  This hook is run before 'x-popup-menu' is about to display a
>>  deck-of-cards menu on screen.
>> 
>> +** New function 'buffer-match-p'
>> +Check if a buffer matches a condition, specified using a DSL.
>
> A "DSL"? what's that?  We don't have that acronym anywhere else in
> Emacs, AFAICS.  Please make that entry more self-explanatory.

It is supposed to mean "Domain Specific Language".  I never noticed that
it wasn't used anywhere else, so sorry about that.  Then again I wasn't
sure how else to put it.  What about

     Can be used to check if buffers satisfy a possibly complex
     condition, [giving a few examples]

Eli Zaretskii <eliz@gnu.org> writes:

>> diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
>> index 43f222d..abc8ada 100644
>> --- a/doc/lispref/windows.texi
>> +++ b/doc/lispref/windows.texi
>> @@ -2596,13 +2596,11 @@ Choosing Window
>> 
>>  @defopt display-buffer-alist
>>  The value of this option is an alist mapping conditions to display
>> -actions.  Each condition may be either a regular expression matching a
>> -buffer name or a function that takes two arguments: a buffer name and
>> -the @var{action} argument passed to @code{display-buffer}.  If either
>> -the name of the buffer passed to @code{display-buffer} matches a
>> -regular expression in this alist, or the function specified by a
>> -condition returns non-@code{nil}, then @code{display-buffer} uses the
>> -corresponding display action to display the buffer.
>> +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-nil value, then
>> +@code{display-buffer} uses the corresponding display action to display
>> +the buffer.
>
> Since buffer-match-p is not documented in the manual, I think this
> change is for the worse, as it leaves CONDITIONS undocumented.  Or am
> I missing something?

No, I haven't written that yet.  This should best be documented in
lispref/buffers.texi, right? 

> In any case, referencing a function without an explicit
> cross-reference is not a good style for the manual, unless the
> function is described in the same node and prior to the reference.
>
> Thanks.

Eli Zaretskii <eliz@gnu.org> writes:

>> diff --git a/lisp/window.el b/lisp/window.el
>> index 2da2f8b..ea90995 100644
>> --- a/lisp/window.el
>> +++ b/lisp/window.el
>> @@ -7495,14 +7495,14 @@ display-buffer-fallback-action
>>  `display-buffer'.")
>>  (put 'display-buffer-fallback-action 'risky-local-variable t)
>> 
>> -(defun display-buffer-assq-regexp (buffer-name alist action)
>> +(defun display-buffer-assq-regexp (buffer-or-name alist action)
>>    "Retrieve ALIST entry corresponding to BUFFER-NAME.
>> -This returns the cdr of the alist entry ALIST if either its key
>> -satisfied a BUFFER-NAME per `buffer-match'.  ACTION should have
>> -the form of the action argument passed to `display-buffer'."
>> +This returns the cdr of the alist entry ALIST if key and
>> +buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
>> +form of the action argument passed to `display-buffer'."
>
> I fixed some minor issues with the modified doc string, but that still
> leaves one question unanswered: what does this function return if no
> alist entry satisfies buffer-match-p?  That should be documented.

  ... If no entry is found, nil is returned?

> Thanks.

-- 
	Philip Kaludercic

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sat, 16 Apr 2022 09:53:26 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> +** New function 'buffer-match-p'
> >> +Check if a buffer matches a condition, specified using a DSL.
> >
> > A "DSL"? what's that?  We don't have that acronym anywhere else in
> > Emacs, AFAICS.  Please make that entry more self-explanatory.
> 
> It is supposed to mean "Domain Specific Language".  I never noticed that
> it wasn't used anywhere else, so sorry about that.  Then again I wasn't
> sure how else to put it.  What about
> 
>      Can be used to check if buffers satisfy a possibly complex
>      condition, [giving a few examples]

Just "satisfies some conditions" (with examples) should be fine, IMO.

> > Since buffer-match-p is not documented in the manual, I think this
> > change is for the worse, as it leaves CONDITIONS undocumented.  Or am
> > I missing something?
> 
> No, I haven't written that yet.  This should best be documented in
> lispref/buffers.texi, right? 

Probably in "Buffer List", yes.

> >> -(defun display-buffer-assq-regexp (buffer-name alist action)
> >> +(defun display-buffer-assq-regexp (buffer-or-name alist action)
> >>    "Retrieve ALIST entry corresponding to BUFFER-NAME.
> >> -This returns the cdr of the alist entry ALIST if either its key
> >> -satisfied a BUFFER-NAME per `buffer-match'.  ACTION should have
> >> -the form of the action argument passed to `display-buffer'."
> >> +This returns the cdr of the alist entry ALIST if key and
> >> +buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
> >> +form of the action argument passed to `display-buffer'."
> >
> > I fixed some minor issues with the modified doc string, but that still
> > leaves one question unanswered: what does this function return if no
> > alist entry satisfies buffer-match-p?  That should be documented.
> 
>   ... If no entry is found, nil is returned?

That's fine, but please avoid passive tense.  Something like

  If no matching entry is found in ALIST, return nil.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 2247 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 16 Apr 2022 09:53:26 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> +** New function 'buffer-match-p'
>> >> +Check if a buffer matches a condition, specified using a DSL.
>> >
>> > A "DSL"? what's that?  We don't have that acronym anywhere else in
>> > Emacs, AFAICS.  Please make that entry more self-explanatory.
>> 
>> It is supposed to mean "Domain Specific Language".  I never noticed that
>> it wasn't used anywhere else, so sorry about that.  Then again I wasn't
>> sure how else to put it.  What about
>> 
>>      Can be used to check if buffers satisfy a possibly complex
>>      condition, [giving a few examples]
>
> Just "satisfies some conditions" (with examples) should be fine, IMO.
>
>> > Since buffer-match-p is not documented in the manual, I think this
>> > change is for the worse, as it leaves CONDITIONS undocumented.  Or am
>> > I missing something?
>> 
>> No, I haven't written that yet.  This should best be documented in
>> lispref/buffers.texi, right? 
>
> Probably in "Buffer List", yes.
>
>> >> -(defun display-buffer-assq-regexp (buffer-name alist action)
>> >> +(defun display-buffer-assq-regexp (buffer-or-name alist action)
>> >>    "Retrieve ALIST entry corresponding to BUFFER-NAME.
>> >> -This returns the cdr of the alist entry ALIST if either its key
>> >> -satisfied a BUFFER-NAME per `buffer-match'.  ACTION should have
>> >> -the form of the action argument passed to `display-buffer'."
>> >> +This returns the cdr of the alist entry ALIST if key and
>> >> +buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
>> >> +form of the action argument passed to `display-buffer'."
>> >
>> > I fixed some minor issues with the modified doc string, but that still
>> > leaves one question unanswered: what does this function return if no
>> > alist entry satisfies buffer-match-p?  That should be documented.
>> 
>>   ... If no entry is found, nil is returned?
>
> That's fine, but please avoid passive tense.  Something like
>
>   If no matching entry is found in ALIST, return nil.

Before I push something I should fix, I'll attach my proposed changes
here:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Further-improve-buffer-match-p-related-documentation.patch --]
[-- Type: text/x-diff, Size: 4064 bytes --]

From 4aa5fecf89d0aae084eb12ba5b2651b6fd9dc991 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sun, 17 Apr 2022 01:11:06 +0200
Subject: [PATCH] Further improve buffer-match-p related documentation

* doc/lispref/buffers.texi (Buffer List): Add entries for
* buffer-match-p and match-buffers
* etc/NEWS: Give examples for buffer-match-p conditions
* lisp/window.el (display-buffer-assq-regexp): Mention what happens
when no entry in the alist satisfies a condition.
---
 doc/lispref/buffers.texi | 41 ++++++++++++++++++++++++++++++++++++++++
 etc/NEWS                 |  6 +++++-
 lisp/window.el           |  3 ++-
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1fe5a60b35..0004f255fe 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -953,6 +953,47 @@ Buffer List
 infinite recursion.
 @end defvar
 
+@defun buffer-match-p condition buffer-or-name arg
+This function can be used to check if a buffer designated by
+@code{buffer-or-name} satisfies a @code{condition}.  An optional third
+argument @code{arg} can be passed on to predicate functions.  A
+predicate can be one of the following:
+@itemize @bullet{}
+@item
+A string containing a regular expression.  The buffer satisfies the
+predicate if the regular expression matches the buffer name.
+@item
+A function that is passed the buffer, and is satisfied if the function
+returns a non-nil value.  The first argument is always the buffer, and
+if the function accepts two arguments (as per @code{func-arity}), the
+third argument to @code{buffer-match-p} will be passed on to the
+predicate function.
+@item
+A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
+@table @code
+@item not
+Satisfied if @code{DATA} doesn't satisfy @code{buffer-match-p} with
+the same buffer and @code{arg}.
+@item or
+Satisfied if @code{DATA} is a list and @emph{any} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@item and
+Satisfied if @code{DATA} is a list and @emph{all} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@end table
+@end itemize
+@end defun
+
+@defun match-buffers condition buffer-list arg
+This function returns a list of all buffers that satisfy a
+@code{condition}, as defined for @code{buffer-match-p}.  By default
+all buffers are considered, but this can be restricted via the second
+optional @code{buffer-list} argument.  Optionally, a third argument
+@code{arg} is passed on to @code{buffer-match-p}.
+@end defun
+
 @node Creating Buffers
 @section Creating Buffers
 @cindex creating buffers
diff --git a/etc/NEWS b/etc/NEWS
index 14d970fe11..fb26ca64f8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1493,7 +1493,11 @@ This hook is run before 'x-popup-menu' is about to display a
 deck-of-cards menu on screen.
 
 ** New function 'buffer-match-p'
-Check if a buffer matches a condition, specified using a DSL.
+Check if a buffer satisfies some condition.  Some examples for
+conditions can be regular expressions that match a buffer name, a
+cons-cell like (major-mode . shell-mode) that matches any buffer where
+major-mode is shell-mode or a combined with a condition like (and
+"\\`\\*.+\\*\\'" (major-mode . special-mode)).
 
 ** New function 'match-buffers'
 Use 'buffer-match-p' to gather a list of buffers that match a
diff --git a/lisp/window.el b/lisp/window.el
index ea90995541..b7503ac999 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7499,7 +7499,8 @@ display-buffer-assq-regexp
   "Retrieve ALIST entry corresponding to BUFFER-NAME.
 This returns the cdr of the alist entry ALIST if key and
 buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
-form of the action argument passed to `display-buffer'."
+form of the action argument passed to `display-buffer'.
+If no matching entry is found in ALIST, return nil."
   (catch 'match
     (dolist (entry alist)
       (when (buffer-match-p (car entry) buffer-or-name action)
-- 
2.30.2


[-- Attachment #3: Type: text/plain, Size: 24 bytes --]


-- 
	Philip Kaludercic

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sat, 16 Apr 2022 23:11:59 +0000
> 
> Before I push something I should fix, I'll attach my proposed changes
> here:

Thanks.

> +@defun buffer-match-p condition buffer-or-name arg
> +This function can be used to check if a buffer designated by

I'd drop "can be used", because that's the function's purpose.
Instead, I'd say "This function checks whether a buffer...".

> +                                                     An optional third
> +argument @code{arg} can be passed on to predicate functions.

Another unnecessary "can".  Suggest to rephrase:

  Optional third argument @var{arg} is passed to the predicate
  function in @var{condition}.

This also means you should have &optional in the @defun line:

  @defun buffer-match-p condition buffer-or-name &optional arg

> +                                                              A
> +predicate can be one of the following:

This suddenly starts talking about "predicates" out of the blue, when
the function's argument is named "condition".  So something is missing
here to connect between the two.

> +@itemize @bullet{}
> +@item
> +A string containing a regular expression.

"Containing"?  I think you mean to say "A string that is interpreted
as a regular expression".

> +A function that is passed the buffer, and is satisfied if the function
> +returns a non-nil value.  The first argument is always the buffer, and
> +if the function accepts two arguments (as per @code{func-arity}), the
> +third argument to @code{buffer-match-p} will be passed on to the
> +predicate function.

I would suggest

  A function, which should return non-@code{nil} if the buffer
  matches.  If the function expects one argument, it is called with
  @var{buffer-or-name} as the argument; if it expects 2 arguments, the
  first argument is @var{buffer-or-name} and the second is @var{arg}
  (or @code{nil} if @var{arg} is omitted).

> +@item
> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of

Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
use @var{lower-case}.

Also, I don't think TYPE and DATA are good labels for what you
describe below.  How about OPER and EXPR instead?

> +@defun match-buffers condition buffer-list arg

&optional is missing.

> +This function returns a list of all buffers that satisfy a
> +@code{condition}, as defined for @code{buffer-match-p}.  By default
> +all buffers are considered, but this can be restricted via the second
> +optional @code{buffer-list} argument.  Optionally, a third argument
> +@code{arg} is passed on to @code{buffer-match-p}.

The last sentence is better rephrased as

  Optional third argument @var{arg} will be used by @var{condition} in
  the same way as @code{buffer-match-p} does.

>  ** New function 'buffer-match-p'
> -Check if a buffer matches a condition, specified using a DSL.
> +Check if a buffer satisfies some condition.  Some examples for
> +conditions can be regular expressions that match a buffer name, a
> +cons-cell like (major-mode . shell-mode) that matches any buffer where
> +major-mode is shell-mode or a combined with a condition like (and
> +"\\`\\*.+\\*\\'" (major-mode . special-mode)).

Please capitalize "major-mode" and "special-mode", as those stand for
something else.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 16 Apr 2022 23:11:59 +0000
>> 
>> Before I push something I should fix, I'll attach my proposed changes
>> here:
>
> Thanks.
>
>> +@defun buffer-match-p condition buffer-or-name arg
>> +This function can be used to check if a buffer designated by
>
> I'd drop "can be used", because that's the function's purpose.
> Instead, I'd say "This function checks whether a buffer...".
>
>> +                                                     An optional third
>> +argument @code{arg} can be passed on to predicate functions.
>
> Another unnecessary "can".  Suggest to rephrase:
>
>   Optional third argument @var{arg} is passed to the predicate
>   function in @var{condition}.
>
> This also means you should have &optional in the @defun line:
>
>   @defun buffer-match-p condition buffer-or-name &optional arg
>
>> +                                                              A
>> +predicate can be one of the following:
>
> This suddenly starts talking about "predicates" out of the blue, when
> the function's argument is named "condition".  So something is missing
> here to connect between the two.
>
>> +@itemize @bullet{}
>> +@item
>> +A string containing a regular expression.
>
> "Containing"?  I think you mean to say "A string that is interpreted
> as a regular expression".
>
>> +A function that is passed the buffer, and is satisfied if the function
>> +returns a non-nil value.  The first argument is always the buffer, and
>> +if the function accepts two arguments (as per @code{func-arity}), the
>> +third argument to @code{buffer-match-p} will be passed on to the
>> +predicate function.
>
> I would suggest
>
>   A function, which should return non-@code{nil} if the buffer
>   matches.  If the function expects one argument, it is called with
>   @var{buffer-or-name} as the argument; if it expects 2 arguments, the
>   first argument is @var{buffer-or-name} and the second is @var{arg}
>   (or @code{nil} if @var{arg} is omitted).
>
>> +@item
>> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
>
> Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
> use @var{lower-case}.
>
> Also, I don't think TYPE and DATA are good labels for what you
> describe below.  How about OPER and EXPR instead?
>
>> +@defun match-buffers condition buffer-list arg
>
> &optional is missing.
>
>> +This function returns a list of all buffers that satisfy a
>> +@code{condition}, as defined for @code{buffer-match-p}.  By default
>> +all buffers are considered, but this can be restricted via the second
>> +optional @code{buffer-list} argument.  Optionally, a third argument
>> +@code{arg} is passed on to @code{buffer-match-p}.
>
> The last sentence is better rephrased as
>
>   Optional third argument @var{arg} will be used by @var{condition} in
>   the same way as @code{buffer-match-p} does.

I cannot object to any of this, and have made the changes.

>>  ** New function 'buffer-match-p'
>> -Check if a buffer matches a condition, specified using a DSL.
>> +Check if a buffer satisfies some condition.  Some examples for
>> +conditions can be regular expressions that match a buffer name, a
>> +cons-cell like (major-mode . shell-mode) that matches any buffer where
>> +major-mode is shell-mode or a combined with a condition like (and
>> +"\\`\\*.+\\*\\'" (major-mode . special-mode)).
>
> Please capitalize "major-mode" and "special-mode", as those stand for
> something else.

I am not sure I follow you, (major-mode . special-mode) is a condition
that checks if a buffer derives from `special-mode'.  If capitalised, it
wouldn't do what it should (or rather it would just be ignored).

-- 
	Philip Kaludercic

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sun, 17 Apr 2022 08:48:51 +0000
> 
> >>  ** New function 'buffer-match-p'
> >> -Check if a buffer matches a condition, specified using a DSL.
> >> +Check if a buffer satisfies some condition.  Some examples for
> >> +conditions can be regular expressions that match a buffer name, a
> >> +cons-cell like (major-mode . shell-mode) that matches any buffer where
> >> +major-mode is shell-mode or a combined with a condition like (and
> >> +"\\`\\*.+\\*\\'" (major-mode . special-mode)).
> >
> > Please capitalize "major-mode" and "special-mode", as those stand for
> > something else.
> 
> I am not sure I follow you, (major-mode . special-mode) is a condition
> that checks if a buffer derives from `special-mode'.  If capitalised, it
> wouldn't do what it should (or rather it would just be ignored).

Sorry, I was confused.  Ignore that part.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> +@item
>> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
>
> Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
> use @var{lower-case}.

Actually on this point I have one more question, is

        @code{(@var{oper} . @var{expr})}

or

        (@var{oper} . @var{expr})

to be preferred?

-- 
	Philip Kaludercic

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sun, 17 Apr 2022 09:02:42 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> +@item
> >> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
> >
> > Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
> > use @var{lower-case}.
> 
> Actually on this point I have one more question, is
> 
>         @code{(@var{oper} . @var{expr})}
> 
> or
> 
>         (@var{oper} . @var{expr})
> 
> to be preferred?

The former, because we still want the parentheses and the period be
typeset in the typeface suitable for code symbols.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sun, 17 Apr 2022 09:02:42 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> +@item
>> >> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
>> >
>> > Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
>> > use @var{lower-case}.
>> 
>> Actually on this point I have one more question, is
>> 
>>         @code{(@var{oper} . @var{expr})}
>> 
>> or
>> 
>>         (@var{oper} . @var{expr})
>> 
>> to be preferred?
>
> The former, because we still want the parentheses and the period be
> typeset in the typeface suitable for code symbols.

Ok, thank you.  I've pushed the changes.

-- 
	Philip Kaludercic

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
> index 43f222d..abc8ada 100644
> --- a/doc/lispref/windows.texi
> +++ b/doc/lispref/windows.texi
> @@ -2596,13 +2596,11 @@ Choosing Window
> 
>  @defopt display-buffer-alist
>  The value of this option is an alist mapping conditions to display
> -actions.  Each condition may be either a regular expression matching a
> -buffer name or a function that takes two arguments: a buffer name and
> -the @var{action} argument passed to @code{display-buffer}.  If either
> -the name of the buffer passed to @code{display-buffer} matches a
> -regular expression in this alist, or the function specified by a
> -condition returns non-@code{nil}, then @code{display-buffer} uses the
> -corresponding display action to display the buffer.
> +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-nil value, then
> +@code{display-buffer} uses the corresponding display action to display
> +the buffer.

Since buffer-match-p is not documented in the manual, I think this
change is for the worse, as it leaves CONDITIONS undocumented.  Or am
I missing something?

In any case, referencing a function without an explicit
cross-reference is not a good style for the manual, unless the
function is described in the same node and prior to the reference.

Thanks.

Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> diff --git a/lisp/window.el b/lisp/window.el
> index 2da2f8b..ea90995 100644
> --- a/lisp/window.el
> +++ b/lisp/window.el
> @@ -7495,14 +7495,14 @@ display-buffer-fallback-action
>  `display-buffer'.")
>  (put 'display-buffer-fallback-action 'risky-local-variable t)
> 
> -(defun display-buffer-assq-regexp (buffer-name alist action)
> +(defun display-buffer-assq-regexp (buffer-or-name alist action)
>    "Retrieve ALIST entry corresponding to BUFFER-NAME.
> -This returns the cdr of the alist entry ALIST if either its key
> -satisfied a BUFFER-NAME per `buffer-match'.  ACTION should have
> -the form of the action argument passed to `display-buffer'."
> +This returns the cdr of the alist entry ALIST if key and
> +buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
> +form of the action argument passed to `display-buffer'."

I fixed some minor issues with the modified doc string, but that still
leaves one question unanswered: what does this function return if no
alist entry satisfies buffer-match-p?  That should be documented.

Thanks.