From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: master c3ab8f1: Improve buffer-match-p documentation Date: Sun, 17 Apr 2022 08:48:51 +0000 Message-ID: <87lew4f630.fsf@posteo.net> References: <83fsmd1lje.fsf@gnu.org> <87sfqdicbt.fsf@posteo.net> <837d7p1eer.fsf@gnu.org> <87bkx0ipxc.fsf@posteo.net> <835yn8yzwd.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21033"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Apr 17 10:53:54 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ng0fI-0005Jw-UW for ged-emacs-devel@m.gmane-mx.org; Sun, 17 Apr 2022 10:53:53 +0200 Original-Received: from localhost ([::1]:51216 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ng0fH-0001w5-Fh for ged-emacs-devel@m.gmane-mx.org; Sun, 17 Apr 2022 04:53:51 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46028) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ng0aX-0008J1-Ds for emacs-devel@gnu.org; Sun, 17 Apr 2022 04:48:59 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:38645) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ng0aV-0005w0-6d for emacs-devel@gnu.org; Sun, 17 Apr 2022 04:48:57 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 3B46E240026 for ; Sun, 17 Apr 2022 10:48:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1650185333; bh=VVouLtRVac8CGC1479HMUUr4b2/dszuQZldJcU6pbAk=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=FKMl1M+ugZnKp0QVvSF/Ma6SClGXG+ygWTXCdjoLQy/iRKMxUEy3JijwcCGMFNT8h ge5/6Wnt2zQDwpAzEswypvRqDe7uQvqhd7Bmz6vQkP0nKWf8KJCKy5+0oEqi7/7xqw z+11L5JzxoP2KF0BmE92risRIzgXV9cuZd7J/yHfOK+pa0kcxVkJ3f+KVn46Duwm78 8lyO449uq192QAShsVeEn05y4dXP0BMiQbeZh9hHbSSLuXZHfhNoP2+LoTsiqLTckl ajbpWgU1M0cOl+l2sQhYtPLXNrt0sjtF1gsq4ian3gm3L0DWSonb9A1VCRPtJRbC78 k+uxn6orS7eaA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Kh3dJ4gkbz9rxH; Sun, 17 Apr 2022 10:48:52 +0200 (CEST) Autocrypt: addr=philipk@posteo.net; prefer-encrypt=nopreference; keydata= mDMEYHHqUhYJKwYBBAHaRw8BAQdAp3GdmYJ6tm5McweY6dEvIYIiry+Oz9rU4MH6NHWK0Ee0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiQBBMWCAA4FiEEDM2H44ZoPt9Ms0eHtVrAHPRh1FwFAmBx6lICGwMFCwkIBwIGFQoJ CAsCBBYCAwECHgECF4AACgkQtVrAHPRh1FyTkgEAjlbGPxFchvMbxzAES3r8QLuZgCxeAXunM9gh io0ePtUBALVhh9G6wIoZhl0gUCbQpoN/UJHI08Gm1qDob5zDxnIHuDgEYHHqUhIKKwYBBAGXVQEF AQEHQNcRB+MUimTMqoxxMMUERpOR+Q4b1KgncDZkhrO2ql1tAwEIB4h4BBgWCAAgFiEEDM2H44Zo Pt9Ms0eHtVrAHPRh1FwFAmBx6lICGwwACgkQtVrAHPRh1Fw1JwD/Qo7kvtib8jy7puyWrSv0MeTS g8qIxgoRWJE/KKdkCLEA/jb9b9/g8nnX+UcwHf/4VfKsjExlnND3FrBviXUW6NcB In-Reply-To: <835yn8yzwd.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Apr 2022 09:42:10 +0300") Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:288533 Archived-At: Eli Zaretskii writes: >> From: Philip Kaludercic >> 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