From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Arun Isaac Newsgroups: gmane.emacs.bugs Subject: bug#40202: directory-files-recursively docstring unclear about include-directories Date: Tue, 24 Mar 2020 13:52:34 +0530 Message-ID: References: <83blombfjk.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="100268"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 40202@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Mar 24 09:23:16 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1jGeqB-000PyS-RK for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 24 Mar 2020 09:23:15 +0100 Original-Received: from localhost ([::1]:44272 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jGeqA-00056M-R8 for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 24 Mar 2020 04:23:14 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35910) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jGepz-000540-FT for bug-gnu-emacs@gnu.org; Tue, 24 Mar 2020 04:23:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jGepy-0004Qh-Fq for bug-gnu-emacs@gnu.org; Tue, 24 Mar 2020 04:23:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:47867) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jGepy-0004Qd-DX for bug-gnu-emacs@gnu.org; Tue, 24 Mar 2020 04:23:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jGepy-00089l-AU for bug-gnu-emacs@gnu.org; Tue, 24 Mar 2020 04:23:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Arun Isaac Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 24 Mar 2020 08:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 40202 X-GNU-PR-Package: emacs Original-Received: via spool by 40202-submit@debbugs.gnu.org id=B40202.158503816931308 (code B ref 40202); Tue, 24 Mar 2020 08:23:02 +0000 Original-Received: (at 40202) by debbugs.gnu.org; 24 Mar 2020 08:22:49 +0000 Original-Received: from localhost ([127.0.0.1]:53840 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jGepl-00088u-6k for submit@debbugs.gnu.org; Tue, 24 Mar 2020 04:22:49 -0400 Original-Received: from mugam.systemreboot.net ([139.59.75.54]:53068) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jGepi-00088k-GO for 40202@debbugs.gnu.org; Tue, 24 Mar 2020 04:22:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=systemreboot.net; s=default; h=Content-Type:MIME-Version:Message-ID:Date: References:In-Reply-To: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=Cuy4ox9B7rqoGWGUElCj5CHhQSBO1qsU3Mdsp8neKTY=; b=aZA1ICA7D+HRqSWUaf1wHBTXR /LBZmL/J5PuGgtO6RuUGRgGhAeM6YQBX+EfkmbzDckOFIlynJG23IYlXMZUKlsqSYUg6dUhJNhPrI t/ib1Ws4uH+pf9s6Bn+E4obU0brgl5kEjQHYdMIdexU4NpH8cNn/uQLNw1p0CLxMbgy4Y=; Original-Received: from [192.168.2.1] (helo=steel) by systemreboot.net with esmtpsa (TLS1.3) tls TLS_AES_256_GCM_SHA384 (Exim 4.93) (envelope-from ) id 1jGepf-003rmH-Fn; Tue, 24 Mar 2020 13:52:43 +0530 In-Reply-To: <83blombfjk.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:177670 Archived-At: --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable >> The docstring of directory-file-recursively in lisp/files.el is unclear >> about the include-directories optional argument. It currently reads >>=20 >> "Optional argument INCLUDE-DIRECTORIES non-nil means also include >> in the output directories whose names match REGEXP." >>=20 >> Perhaps this could be rewritten as >>=20 >> "If optional argument INCLUDE-DIRECTORIES is non-nil, the returned list >> also includes directories whose names match REGEXP." > > Could you please explain which part(s) of the proposed doc string make > the issue more clear for you? To me both variants sound equivalent. They seem equivalent once you already know the meaning that is supposed to be conveyed. I had to wrack my brains for a while before I understood what that sentence means. 1. It is not immediately clear how to parse the original docstring. Is it parsed as "(include) (in the output directories whose name matches REGEXP)", "(include in the output directories) (whose name matches REGEXP)" or "(include in the output) (directories whose name matches REGEXP)"? The phrase "in the output" in between the sentence makes it difficult to parse. Some punctuation there could have helped, but I don't see how to do that. 2. The grammar of my proposal is better. In the original, the usage of "means" as the predicate, "optional argument INCLUDE-DIRECTORIES non-nil" as the subject is unusual and awkward. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCAAdFiEEf3MDQ/Lwnzx3v3nTLiXui2GAK7MFAl55w0oACgkQLiXui2GA K7PhDggAqvTYXO25D39/c17i9bpSFvixnNbK4dzm61TQ4dZGyEoL7q9rOB8pAoV2 GN8llr+uuCbCPSI/SwrxKILBIfxMCRKcDI6CvPjzGynfSJWSR2IPBsEOgio392ft RS9LmvR2QPCwI74wRBBryOwNXa3NqU5cSHC85iO/Xkp5rjrndCz5XbLnrrI+spEt uP7tIjRKO5bM6ZgKmDQgfmyVjiLyh7Ztic8HXKtCsK1fuy664UREe2nEeEGjakPD IruykmfMnWRevMZTP8+5r9ZFAQkz4v5Lv4IRw4rI4ca4+sLQUqV6IFO5VXYX71Nm zS9MGgFT8ECeVRw0n5BBay7323RWrQ== =1c5O -----END PGP SIGNATURE----- --=-=-=--