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: Sun, 17 Apr 2022 08:48:51 +0000 [thread overview]
Message-ID: <87lew4f630.fsf@posteo.net> (raw)
In-Reply-To: <835yn8yzwd.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Apr 2022 09:42:10 +0300")
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
next prev parent reply other threads:[~2022-04-17 8:48 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
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 [this message]
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87lew4f630.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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.