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