From: Philip Kaludercic <philipk@posteo.net>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: master c3ab8f1: Improve buffer-match-p documentation
Date: Sat, 16 Apr 2022 09:53:26 +0000 [thread overview]
Message-ID: <87sfqdicbt.fsf@posteo.net> (raw)
In-Reply-To: <83fsmd1lje.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 16 Apr 2022 11:26:29 +0300")
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
next prev parent reply other threads:[~2022-04-16 9:53 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-16 8:26 master c3ab8f1: Improve buffer-match-p documentation Eli Zaretskii
2022-04-16 9:53 ` Philip Kaludercic [this message]
2022-04-16 11:00 ` Eli Zaretskii
2022-04-16 23:11 ` Philip Kaludercic
2022-04-17 6:42 ` Eli Zaretskii
2022-04-17 8:48 ` Philip Kaludercic
2022-04-17 11:30 ` Eli Zaretskii
2022-04-17 9:02 ` Philip Kaludercic
2022-04-17 11:31 ` Eli Zaretskii
2022-04-17 12:06 ` Philip Kaludercic
-- strict thread matches above, loose matches on Subject: below --
2022-04-16 8:34 Eli Zaretskii
2022-04-16 8:40 Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87sfqdicbt.fsf@posteo.net \
--to=philipk@posteo.net \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).