Received: (at 52202) by debbugs.gnu.org; 1 Dec 2021 19:49:32 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Wed Dec 01 14:49:32 2021 Received: from localhost ([127.0.0.1]:45763 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1msVbg-0005tf-45 for submit <at> debbugs.gnu.org; Wed, 01 Dec 2021 14:49:32 -0500 Received: from relay1-d.mail.gandi.net ([217.70.183.193]:59979) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <matt@HIDDEN>) id 1msVbd-0005tQ-Vm for 52202 <at> debbugs.gnu.org; Wed, 01 Dec 2021 14:49:30 -0500 Received: (Authenticated sender: matt@HIDDEN) by relay1-d.mail.gandi.net (Postfix) with ESMTPSA id 21F3C240005; Wed, 1 Dec 2021 19:49:22 +0000 (UTC) Received: from matt by naz with local (Exim 4.95) (envelope-from <matt@HIDDEN>) id 1msVbT-000NUi-Nw; Wed, 01 Dec 2021 11:49:19 -0800 From: Matt Armstrong <matt@HIDDEN> To: Lars Ingebrigtsen <larsi@HIDDEN> Subject: Re: bug#52202: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings In-Reply-To: <87v909asf2.fsf@HIDDEN> References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN> <83czmhtp9v.fsf@HIDDEN> <87wnkpidim.fsf_-_@HIDDEN> <87v909asf2.fsf@HIDDEN> Date: Wed, 01 Dec 2021 11:49:19 -0800 Message-ID: <87y25414xs.fsf@HIDDEN> MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 52202 Cc: 52202 <at> debbugs.gnu.org, Eli Zaretskii <eliz@HIDDEN> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.7 (-) Lars Ingebrigtsen <larsi@HIDDEN> writes: > Matt Armstrong <matt@HIDDEN> writes: > >> Then I realized that the lisp reference manual is in good shape. This >> patch copies text almost verbatim from it. So, the diff is both large >> but hopefully not hard to verify in review. > > In these cases, we usually just say "See (elisp)Section" in the doc > strings, and leave the description of the complex data structures to > the manual. I can see it both ways. Eli suggested that a complete docstring would be more handy (up thread), and I now think this might be achievable with simpler edits, so absent a different consensus I'll go that direction for now.
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.
Received: (at 52202) by debbugs.gnu.org; 1 Dec 2021 19:43:29 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Dec 01 14:43:29 2021
Received: from localhost ([127.0.0.1]:45730 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1msVVp-0003Rr-8W
for submit <at> debbugs.gnu.org; Wed, 01 Dec 2021 14:43:29 -0500
Received: from relay2-d.mail.gandi.net ([217.70.183.194]:49379)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <matt@HIDDEN>) id 1msVVm-0003Re-Vg
for 52202 <at> debbugs.gnu.org; Wed, 01 Dec 2021 14:43:27 -0500
Received: (Authenticated sender: matt@HIDDEN)
by relay2-d.mail.gandi.net (Postfix) with ESMTPSA id 7A3E040002;
Wed, 1 Dec 2021 19:43:20 +0000 (UTC)
Received: from matt by naz with local (Exim 4.95)
(envelope-from <matt@HIDDEN>) id 1msVVd-000NU8-6V;
Wed, 01 Dec 2021 11:43:17 -0800
From: Matt Armstrong <matt@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#52202: 29.0.50; try-completion, all-completions support for
a list of strings COLLECTION is not documented in their docstrings
In-Reply-To: <83sfvdro6q.fsf@HIDDEN>
References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN>
<83czmhtp9v.fsf@HIDDEN> <87wnkpidim.fsf_-_@HIDDEN>
<83sfvdro6q.fsf@HIDDEN>
Date: Wed, 01 Dec 2021 11:43:17 -0800
Message-ID: <871r2w2jsa.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 52202
Cc: 52202 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)
Eli Zaretskii <eliz@HIDDEN> writes:
>> Thanks Eli, I can sympathize with respect to the review difficulty, but
>> I couldn't find a simple edit that did a good job. It is more than just
>> "list of strings", but I did not realize when I filed the bug. This
>> became clear only after I started reading code and trying to document
>> the current behavior.
>
> Can you list the aspects which the current doc string doesn't
> describe, or describes inaccurately or incorrectly?
Good question; maybe I went overboard. Quotes below are from the
current docstring:
> If COLLECTION is an alist, the keys (cars of elements) are the
> possible completions. If an element is not a cons cell, then the
> element itself is the possible completion.
I find this confusing because "If COLLECTION is an alist" strongly leads
the reader away from the idea that "COLLECTION may also be a list of
symbols/strings." So perhaps replace this paragraph with slightly
edited text from the manual:
If COLLECTION is a list (or alist), the permissible completions are
specified by the elements of the list, each of which should be
either a string, or a cons cell whose CAR is either a string or a
symbol. If the list contains elements of any other type, those are
ignored.
> The argument given to PREDICATE is the alist element or the symbol
> from the obarray.
I found this confusing too, for the same reason.
So how about:
The argument given to PREDICATE is either a string, symbol or a cons
cell (the CAR of which is a string or symbol) from the list (or
alist), or a symbol (_not_ a symbol name) from the obarray. If
COLLECTION is a hash table, PREDICATE is called with two arguments,
the string or symbol key and the associated value.
These two blurbs are slight edits from the elisp manual. I think this
new wording would be good in both the doc string and the manual.
If these smaller edits seem good I'm happy to reformulate the patch (I
can update the manual as well).
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.Received: (at 52202) by debbugs.gnu.org; 1 Dec 2021 03:57:33 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 22:57:33 2021 Received: from localhost ([127.0.0.1]:42917 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1msGkO-0002T6-Tw for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 22:57:33 -0500 Received: from quimby.gnus.org ([95.216.78.240]:48486) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <larsi@HIDDEN>) id 1msGkN-0002Sq-7L for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 22:57:31 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=3RPi4RxPDpEfSXVlH26MxKfOkX/2NUstvqy+kLqFhCY=; b=qwK01fSKqXMSYHuG+qkrRDbLMQ NQgLhxjugdigR//9KLr1T3I73SkdW7n7ChnoYKFZstZAO2TeDh9eF/HrhVjk0cngD7oR6lA/s/BuC /cJ2lWRspeU422hYVT8xzkb7ZLWJPu/qmVjjPXPqXXOUU2KKNfUvdcGl7UTVXY6VpRcw=; Received: from [84.212.220.105] (helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from <larsi@HIDDEN>) id 1msGkD-0003uY-Sb; Wed, 01 Dec 2021 04:57:24 +0100 From: Lars Ingebrigtsen <larsi@HIDDEN> To: Matt Armstrong <matt@HIDDEN> Subject: Re: bug#52202: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN> <83czmhtp9v.fsf@HIDDEN> <87wnkpidim.fsf_-_@HIDDEN> X-Now-Playing: Streifenjunko's _Like Driving_: "Like Driving" Date: Wed, 01 Dec 2021 04:57:21 +0100 In-Reply-To: <87wnkpidim.fsf_-_@HIDDEN> (Matt Armstrong's message of "Tue, 30 Nov 2021 12:39:45 -0800") Message-ID: <87v909asf2.fsf@HIDDEN> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Matt Armstrong <matt@HIDDEN> writes: > Then I realized that the lisp reference manual is in good shape. This > patch copies text almost verbatim from it. So, the diff is both large > but hopefully not hard to verify in review. Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 52202 Cc: 52202 <at> debbugs.gnu.org, Eli Zaretskii <eliz@HIDDEN> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) Matt Armstrong <matt@HIDDEN> writes: > Then I realized that the lisp reference manual is in good shape. This > patch copies text almost verbatim from it. So, the diff is both large > but hopefully not hard to verify in review. In these cases, we usually just say "See (elisp)Section" in the doc strings, and leave the description of the complex data structures to the manual. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.Received: (at 52202) by debbugs.gnu.org; 1 Dec 2021 03:37:04 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 22:37:04 2021 Received: from localhost ([127.0.0.1]:42913 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1msGQa-0001yg-6H for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 22:37:04 -0500 Received: from eggs.gnu.org ([209.51.188.92]:53960) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1msGQY-0001yC-Hf for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 22:37:02 -0500 Received: from [2001:470:142:3::e] (port=34638 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1msGQS-0007fN-PF; Tue, 30 Nov 2021 22:36:56 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=CRcN5VbOBl/3P3Uez0Vx4eX34RhXT/XTq4GvFDGuVMI=; b=i9hgnvMOtvxJ U5MVaSzbxVreF0f6zgv6AXF1pzu+B4mpnGjj5FddMZM/J4Pyu+J1jXQIWliIsGNy7RDJogP1y5lB+ AzssVZqJOE0psNItj0KEKW8yQv5KOf4lQQUkZE7yaNF6iTMlKPiUt178pGVTw6Nzyf6RHmGmcbOv7 9p0YdlRaAiqGcPO//tTgL8qOhh3wQSL5VJWgKMQw6bL2ZfKYoN34tLafazMjktF/pRKtIY2V1kkeJ KtCUVYmAtGkIAupcYQY4LQCyDBb2ov9HxdrSc0zLy8GdkHL+tzv3RK4X430acZVtrGrS1gS0Y3pBp TaS2DmoFwBbTiglwrn4uqw==; Received: from [87.69.77.57] (port=2436 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1msGQS-0003Dw-H0; Tue, 30 Nov 2021 22:36:56 -0500 Date: Wed, 01 Dec 2021 05:36:45 +0200 Message-Id: <83sfvdro6q.fsf@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: Matt Armstrong <matt@HIDDEN> In-Reply-To: <87wnkpidim.fsf_-_@HIDDEN> (message from Matt Armstrong on Tue, 30 Nov 2021 12:39:45 -0800) Subject: Re: bug#52202: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN> <83czmhtp9v.fsf@HIDDEN> <87wnkpidim.fsf_-_@HIDDEN> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 52202 Cc: 52202 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) > From: Matt Armstrong <matt@HIDDEN> > Cc: 52202 <at> debbugs.gnu.org > Date: Tue, 30 Nov 2021 12:39:45 -0800 > > Eli Zaretskii <eliz@HIDDEN> writes: > > >> From: Matt Armstrong <matt@HIDDEN> > >> Date: Tue, 30 Nov 2021 11:18:05 -0800 > >> > >> Attached is a docstring patch against the emacs-28 branch for this > >> issue. > > > > Thanks, but ... all these changes just to say that a list of strings > > can also be a COLLECTION? This looks like a complete rewrite, and > > comparing it with the existing doc string is a lot of work. Is the > > current doc string really that awful and requires such a complete > > rewrite? Why can't we get away with a smaller, simpler change (that > > would be easier to review and approve)? > > Thanks Eli, I can sympathize with respect to the review difficulty, but > I couldn't find a simple edit that did a good job. It is more than just > "list of strings", but I did not realize when I filed the bug. This > became clear only after I started reading code and trying to document > the current behavior. Can you list the aspects which the current doc string doesn't describe, or describes inaccurately or incorrectly? Thanks.
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.
Received: (at 52202) by debbugs.gnu.org; 30 Nov 2021 20:39:57 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 15:39:57 2021
Received: from localhost ([127.0.0.1]:42632 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1ms9uv-00040X-Fk
for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 15:39:57 -0500
Received: from relay8-d.mail.gandi.net ([217.70.183.201]:39929)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <matt@HIDDEN>) id 1ms9ut-00040B-CV
for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 15:39:56 -0500
Received: (Authenticated sender: matt@HIDDEN)
by relay8-d.mail.gandi.net (Postfix) with ESMTPSA id B7D961BF206;
Tue, 30 Nov 2021 20:39:48 +0000 (UTC)
Received: from matt by naz with local (Exim 4.95)
(envelope-from <matt@HIDDEN>) id 1ms9uj-000HYA-Se;
Tue, 30 Nov 2021 12:39:45 -0800
From: Matt Armstrong <matt@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#52202: 29.0.50; try-completion, all-completions support for
a list of strings COLLECTION is not documented in their docstrings
References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN>
<83czmhtp9v.fsf@HIDDEN>
Date: Tue, 30 Nov 2021 12:39:45 -0800
In-Reply-To: <83czmhtp9v.fsf@HIDDEN> (Eli Zaretskii's message of "Tue, 30 Nov
2021 21:30:20 +0200")
Message-ID: <87wnkpidim.fsf_-_@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 52202
Cc: 52202 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)
Eli Zaretskii <eliz@HIDDEN> writes:
>> From: Matt Armstrong <matt@HIDDEN>
>> Date: Tue, 30 Nov 2021 11:18:05 -0800
>>
>> Attached is a docstring patch against the emacs-28 branch for this
>> issue.
>
> Thanks, but ... all these changes just to say that a list of strings
> can also be a COLLECTION? This looks like a complete rewrite, and
> comparing it with the existing doc string is a lot of work. Is the
> current doc string really that awful and requires such a complete
> rewrite? Why can't we get away with a smaller, simpler change (that
> would be easier to review and approve)?
Thanks Eli, I can sympathize with respect to the review difficulty, but
I couldn't find a simple edit that did a good job. It is more than just
"list of strings", but I did not realize when I filed the bug. This
became clear only after I started reading code and trying to document
the current behavior.
Then I realized that the lisp reference manual is in good shape. This
patch copies text almost verbatim from it. So, the diff is both large
but hopefully not hard to verify in review.
Another issue is that these function provide extension points that pass
COLLECTION or elements from it directly to caller-supplied functions.
To write those functions correctly the programmer has to know all the
details of how the default C implementation works if the callbacks are
to work in a robust way. In other words, this docstring is for
completion extension implementers as much as it is for callers. I
figure an exhaustively pedantic approach is justifiable here.
One problem is the semantic complexity of how these functions interpret
COLLECTION. They defy a simple and concise explanation.
E.g. COLLECTION can be...
...a list of strings
...a list of symbols
...an alist whose keys are strings
...an alist whose keys are symbols
...a list whose elements are a mixture of any of the above four
possibilities.
And we have hash tables whose keys are strings, symbols, or a mix...
Also, any PREDICATE is passed the list elements (or hash key/values)
directly, without any symbol->string normalization.
Little of this is clear from the current docstrings, but the lisp ref
does a good job with it.
>> Note/question: I wonder if the `all-completions' docstring should refer
>> to `try-completion' rather than copy much of the text. The same
>> approach works well in the lisp ref manual, I think.
>
> ELisp manual describes both one next to the other, so it can get away
> with such a technique. Doc strings don't have that luxury; referring
> the user to another complex doc string generally raises the bar and
> makes the documentation harder to use, because one needs to constantly
> go back to the original function to figure out how the arguments
> described in the other function are used in the original one. It's
> annoying.
That makes sense, thanks.
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.Received: (at 52202) by debbugs.gnu.org; 30 Nov 2021 19:30:33 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 14:30:33 2021 Received: from localhost ([127.0.0.1]:42548 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1ms8pk-00028y-US for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 14:30:33 -0500 Received: from eggs.gnu.org ([209.51.188.92]:45758) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1ms8pj-00028k-3X for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 14:30:31 -0500 Received: from [2001:470:142:3::e] (port=47772 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1ms8pd-0005xJ-9N; Tue, 30 Nov 2021 14:30:25 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=rucUEYkIlPFSCR5FAGWJnMXNQy4LAn5fu6kVGvyMc9M=; b=UyKntNp60KZl u7i7P2V79htqJqfGDqD3owoun01ofzcFuAWdrXuSHNvW9y89T/oOlR1qC8A2a9+UWDBvmJk07XDW3 SEUP/I6khXwmq3g5mAEKJDOJoCi1K6BIl5td4GGCh4Z6bDEMxn3jSpYnXbhmGJkf46ycu5iYVRA+P uRAbH7BoILSQLJ/09wXs76wj1CR6KtMYYQMwA+oXPC7Fi5abGGXqHWywdYIDCLqjxVWJUZ02if2VW cxmdlrdVUoGppsDOyuxcgMlrPEWG3eOwUbtIyGy8C4Qn5s59YJanRHelp+aELos+TJjk1mrt5KHeW KGcwSMTNsubx+70szR8w/Q==; Received: from [87.69.77.57] (port=4153 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1ms8pd-000664-1p; Tue, 30 Nov 2021 14:30:25 -0500 Date: Tue, 30 Nov 2021 21:30:20 +0200 Message-Id: <83czmhtp9v.fsf@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: Matt Armstrong <matt@HIDDEN> In-Reply-To: <871r2xjvv6.fsf@HIDDEN> (message from Matt Armstrong on Tue, 30 Nov 2021 11:18:05 -0800) Subject: Re: bug#52202: [PATCH] try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings References: <875ys9k2a7.fsf@HIDDEN> <871r2xjvv6.fsf@HIDDEN> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 52202 Cc: 52202 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) > From: Matt Armstrong <matt@HIDDEN> > Date: Tue, 30 Nov 2021 11:18:05 -0800 > > Attached is a docstring patch against the emacs-28 branch for this > issue. Thanks, but ... all these changes just to say that a list of strings can also be a COLLECTION? This looks like a complete rewrite, and comparing it with the existing doc string is a lot of work. Is the current doc string really that awful and requires such a complete rewrite? Why can't we get away with a smaller, simpler change (that would be easier to review and approve)? > Note/question: I wonder if the `all-completions' docstring should refer > to `try-completion' rather than copy much of the text. The same > approach works well in the lisp ref manual, I think. ELisp manual describes both one next to the other, so it can get away with such a technique. Doc strings don't have that luxury; referring the user to another complex doc string generally raises the bar and makes the documentation harder to use, because one needs to constantly go back to the original function to figure out how the arguments described in the other function are used in the original one. It's annoying.
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.
Received: (at 52202) by debbugs.gnu.org; 30 Nov 2021 19:18:18 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 14:18:18 2021
Received: from localhost ([127.0.0.1]:42542 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1ms8dt-0001nu-DM
for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 14:18:17 -0500
Received: from relay11.mail.gandi.net ([217.70.178.231]:45825)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <matt@HIDDEN>) id 1ms8dr-0001nf-0N
for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 14:18:16 -0500
Received: (Authenticated sender: matt@HIDDEN)
by relay11.mail.gandi.net (Postfix) with ESMTPSA id 417FE10000A
for <52202 <at> debbugs.gnu.org>; Tue, 30 Nov 2021 19:18:07 +0000 (UTC)
Received: from matt by naz with local (Exim 4.95)
(envelope-from <matt@HIDDEN>) id 1ms8dh-000HOV-1W
for 52202 <at> debbugs.gnu.org; Tue, 30 Nov 2021 11:18:05 -0800
From: Matt Armstrong <matt@HIDDEN>
To: bug#52202 <52202 <at> debbugs.gnu.org>
Subject: [PATCH] try-completion, all-completions support for a list of
strings COLLECTION is not documented in their docstrings
Date: Tue, 30 Nov 2021 11:18:05 -0800
In-Reply-To: bug's message of "Tue, 30 Nov 2021 19:06:51 +0000"
Message-ID: <871r2xjvv6.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 52202
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)
--=-=-=
Content-Type: text/plain
Attached is a docstring patch against the emacs-28 branch for this
issue.
Note/question: I wonder if the `all-completions' docstring should refer
to `try-completion' rather than copy much of the text. The same
approach works well in the lisp ref manual, I think.
--=-=-=
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: inline;
filename=0001-Improve-the-try-completion-and-all-completions-docst.patch
Content-Transfer-Encoding: quoted-printable
From 8bc1bee134f0626513efd00f4a283cf5a2d2a359 Mon Sep 17 00:00:00 2001
From: Matt Armstrong <matt@HIDDEN>
Date: Tue, 30 Nov 2021 10:54:17 -0800
Subject: [PATCH] Improve the `try-completion' and `all-completions' docstri=
ngs
* src/minibuf.c (Ftry_completion):
(Fall_completions): Use language from the Emacs lisp manual when
talking about the COLLECTION and PREDICATE arguments. Most notably,
the way completion tables may be passed is now more clear. The prior
docstring did not mention lists of strings/symbols at all. Bug#52202
---
src/minibuf.c | 124 +++++++++++++++++++++++++++++++-------------------
1 file changed, 77 insertions(+), 47 deletions(-)
diff --git a/src/minibuf.c b/src/minibuf.c
index 6c0cd358c5..f1ee7b2453 100644
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -1569,34 +1569,49 @@ match_regexps (Lisp_Object string, Lisp_Object rege=
xps,
DEFUN ("try-completion", Ftry_completion, Stry_completion, 2, 3, 0,
doc: /* Return common substring of all completions of STRING in COL=
LECTION.
Test each possible completion specified by COLLECTION
-to see if it begins with STRING. The possible completions may be
-strings or symbols. Symbols are converted to strings before testing,
-see `symbol-name'.
-All that match STRING are compared together; the longest initial sequence
-common to all these matches is the return value.
-If there is no match at all, the return value is nil.
-For a unique match which is exact, the return value is t.
-
-If COLLECTION is an alist, the keys (cars of elements) are the
-possible completions. If an element is not a cons cell, then the
-element itself is the possible completion.
-If COLLECTION is a hash-table, all the keys that are strings or symbols
-are the possible completions.
-If COLLECTION is an obarray, the names of all symbols in the obarray
-are the possible completions.
+to see if it begins with STRING.
=20
-COLLECTION can also be a function to do the completion itself.
-It receives three arguments: the values STRING, PREDICATE and nil.
+All completions that match STRING are compared together; the longest
+initial sequence common to all these matches is the return value. If
+there is no match at all, the return value is nil. For a unique match
+which is exact, the return value is t.
+
+COLLECTION is called the "completion table." Its value must be a
+list, a hash table, an obarray, or a completion function.
+
+If COLLECTION is a list, the possible completions are specified by the
+elements of the list, each of which should be either a string, a
+symbol, or a cons cell whose CAR is either a string or a symbol. If
+the list contains elements of any other type, those are ignored.
+
+If COLLECTION is a hash-table, all the keys that are strings or
+symbols are the possible completions.
+
+If COLLECTION is an obarray, all the symbols in the obarray are the
+possible completions.
+
+The possible completions from COLLECTION that are symbols are
+converted to strings before testing, see `symbol-name'.
+
+COLLECTION can also be a function to do the completion itself. It
+receives three arguments: the values STRING, PREDICATE and nil (the
+third argument is so that the same function can be used in
+=E2=80=98all-completions=E2=80=99 and do the appropriate thing in either c=
ase).
Whatever it returns becomes the value of `try-completion'.
=20
-If optional third argument PREDICATE is non-nil,
-it is used to test each possible match.
-The match is a candidate only if PREDICATE returns non-nil.
-The argument given to PREDICATE is the alist element
-or the symbol from the obarray. If COLLECTION is a hash-table,
-predicate is called with two arguments: the key and the value.
-Additionally to this predicate, `completion-regexp-list'
-is used to further constrain the set of candidates. */)
+If optional third argument PREDICATE is non-nil, it is used to test
+each possible match. The match is a candidate only if PREDICATE
+returns non-nil. The argument given to PREDICATE is an element from
+COLLECTION. If COLLECTION is a list it is a list element (either a
+symbol, string, or cons cell whose CAR is a symbol or string). If
+COLLECTION is an obarray, a symbol from it. If COLLECTION is a
+hash-table, predicate is called with two arguments: a key and the
+value.
+
+In addition, to be acceptable, a completion must also match all the
+regular expressions in =E2=80=98completion-regexp-list=E2=80=99. (Unless =
COLLECTION
+is a function, in which case that function has to handle
+=E2=80=98completion-regexp-list=E2=80=99 itself.) */)
(Lisp_Object string, Lisp_Object collection, Lisp_Object predicate)
{
=20
@@ -1808,31 +1823,46 @@ DEFUN ("try-completion", Ftry_completion, Stry_comp=
letion, 2, 3, 0,
DEFUN ("all-completions", Fall_completions, Sall_completions, 2, 4, 0,
doc: /* Search for partial matches to STRING in COLLECTION.
Test each of the possible completions specified by COLLECTION
-to see if it begins with STRING. The possible completions may be
-strings or symbols. Symbols are converted to strings before testing,
-see `symbol-name'.
-The value is a list of all the possible completions that match STRING.
-
-If COLLECTION is an alist, the keys (cars of elements) are the
-possible completions. If an element is not a cons cell, then the
-element itself is the possible completion.
-If COLLECTION is a hash-table, all the keys that are strings or symbols
-are the possible completions.
-If COLLECTION is an obarray, the names of all symbols in the obarray
-are the possible completions.
+to see if it begins with STRING.
+The value is a list of strings for all the possible completions that
+match STRING.
=20
-COLLECTION can also be a function to do the completion itself.
-It receives three arguments: the values STRING, PREDICATE and t.
+COLLECTION is called the "completion table." Its value must be a
+list, a hash table, an obarray, or a completion function.
+
+If COLLECTION is a list, the permissible completions are specified by
+the elements of the list, each of which should be either a string, a
+symbol, or a cons cell whose CAR is either a string or a symbol. If
+the list contains elements of any other type, those are ignored.
+
+If COLLECTION is a hash-table, all the keys that are strings or
+symbols are the possible completions.
+
+If COLLECTION is an obarray, all the symbols in the obarray are the
+possible completions.
+
+The possible completions from COLLECTION that are symbols are
+converted to strings before testing, see `symbol-name'.
+
+COLLECTION can also be a function to do the completion itself. It
+receives three arguments: the values STRING, PREDICATE and t (the
+third argument is so that the same function can be used in
+=E2=80=98try-completion=E2=80=99 and do the appropriate thing in either ca=
se).
Whatever it returns becomes the value of `all-completions'.
=20
-If optional third argument PREDICATE is non-nil,
-it is used to test each possible match.
-The match is a candidate only if PREDICATE returns non-nil.
-The argument given to PREDICATE is the alist element
-or the symbol from the obarray. If COLLECTION is a hash-table,
-predicate is called with two arguments: the key and the value.
-Additionally to this predicate, `completion-regexp-list'
-is used to further constrain the set of candidates.
+If optional third argument PREDICATE is non-nil, it is used to test
+each possible match. The match is a candidate only if PREDICATE
+returns non-nil. The argument given to PREDICATE is an element from
+COLLECTION. If COLLECTION is a list it is a list element (either a
+symbol, string, or cons cell whose CAR is a symbol or string). If
+COLLECTION is an obarray, a symbol from it. If COLLECTION is a
+hash-table, predicate is called with two arguments: a key and the
+value.
+
+In addition, to be acceptable, a completion must also match all the
+regular expressions in =E2=80=98completion-regexp-list=E2=80=99. (Unless =
COLLECTION
+is a function, in which case that function has to handle
+=E2=80=98completion-regexp-list=E2=80=99 itself.)
=20
An obsolete optional fourth argument HIDE-SPACES is still accepted for
backward compatibility. If non-nil, strings in COLLECTION that start
--=20
2.33.0
--=-=-=--
bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.Received: (at submit) by debbugs.gnu.org; 30 Nov 2021 16:59:43 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 11:59:43 2021 Received: from localhost ([127.0.0.1]:42265 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1ms6Tm-0004AQ-RL for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 11:59:43 -0500 Received: from lists.gnu.org ([209.51.188.17]:41274) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <matt@HIDDEN>) id 1ms6Tl-0004AI-GX for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 11:59:41 -0500 Received: from eggs.gnu.org ([209.51.188.92]:53494) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <matt@HIDDEN>) id 1ms6Tl-0005ng-7Y for bug-gnu-emacs@HIDDEN; Tue, 30 Nov 2021 11:59:41 -0500 Received: from relay12.mail.gandi.net ([217.70.178.232]:45169) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <matt@HIDDEN>) id 1ms6Tj-00074u-5I for bug-gnu-emacs@HIDDEN; Tue, 30 Nov 2021 11:59:40 -0500 Received: (Authenticated sender: matt@HIDDEN) by relay12.mail.gandi.net (Postfix) with ESMTPSA id 1119F200003 for <bug-gnu-emacs@HIDDEN>; Tue, 30 Nov 2021 16:59:31 +0000 (UTC) Received: from matt by naz with local (Exim 4.95) (envelope-from <matt@HIDDEN>) id 1ms6TY-000AbC-OW for bug-gnu-emacs@HIDDEN; Tue, 30 Nov 2021 08:59:28 -0800 From: Matt Armstrong <matt@HIDDEN> To: bug-gnu-emacs@HIDDEN Subject: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings Date: Tue, 30 Nov 2021 08:59:28 -0800 Message-ID: <875ys9k2a7.fsf@HIDDEN> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=217.70.178.232; envelope-from=matt@HIDDEN; helo=relay12.mail.gandi.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.6 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -2.6 (--) `try-completion' and `all-completions' support a completion COLLECTION of a list of strings. This is not documented in their docstrings. This is confusing because every other supported data structure is mentioned. This support was added around 20 years ago. See Stefan's commit 695deb1857 or https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=695deb1857dd95239df0139894e40719699a6cc8 I'm assuming this was just an oversight, since `test-completion' mentions "list of strings" as does the description of `try-completion' in the elisp manual.
Matt Armstrong <matt@HIDDEN>:bug-gnu-emacs@HIDDEN.
Full text available.bug-gnu-emacs@HIDDEN:bug#52202; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.