GNU bug report logs - #40202
directory-files-recursively docstring unclear about include-directories

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 40202 in the body.
You can then email your comments to 40202 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Arun Isaac <arunisaac <at> systemreboot.net>
To: bug-gnu-emacs <at> gnu.org
Subject: directory-files-recursively docstring unclear about
 include-directories
Date: Tue, 24 Mar 2020 02:46:55 +0530

[Message part 1 (text/plain, inline)]

Hi,

The docstring of directory-file-recursively in lisp/files.el is unclear
about the include-directories optional argument. It currently reads

"Optional argument INCLUDE-DIRECTORIES non-nil means also include
in the output directories whose names match REGEXP."

Perhaps this could be rewritten as

"If optional argument INCLUDE-DIRECTORIES is non-nil, the returned list
also includes directories whose names match REGEXP."

Thanks,
Arun

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 40202 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arun Isaac <arunisaac <at> systemreboot.net>
Cc: 40202 <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Tue, 24 Mar 2020 05:25:03 +0200

> From: Arun Isaac <arunisaac <at> systemreboot.net>
> Date: Tue, 24 Mar 2020 02:46:55 +0530
> 
> The docstring of directory-file-recursively in lisp/files.el is unclear
> about the include-directories optional argument. It currently reads
> 
> "Optional argument INCLUDE-DIRECTORIES non-nil means also include
> in the output directories whose names match REGEXP."
> 
> Perhaps this could be rewritten as
> 
> "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.

Message #11 received at 40202 <at> debbugs.gnu.org (full text, mbox):

From: Arun Isaac <arunisaac <at> systemreboot.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 40202 <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Tue, 24 Mar 2020 13:52:34 +0530

[Message part 1 (text/plain, inline)]

>> The docstring of directory-file-recursively in lisp/files.el is unclear
>> about the include-directories optional argument. It currently reads
>> 
>> "Optional argument INCLUDE-DIRECTORIES non-nil means also include
>> in the output directories whose names match REGEXP."
>> 
>> Perhaps this could be rewritten as
>> 
>> "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.

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 40202 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Arun Isaac <arunisaac <at> systemreboot.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 40202 <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Tue, 24 Mar 2020 22:23:14 +0100

Arun Isaac <arunisaac <at> systemreboot.net> writes:

> 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.

Yes, I agree that your version is much clearer and easier to understand.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #17 received at 40202 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Nordin <tomasn <at> posteo.net>
To: Arun Isaac <arunisaac <at> systemreboot.net>, 40202 <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Wed, 25 Mar 2020 18:20:06 +0100

Arun Isaac <arunisaac <at> systemreboot.net> writes:

> Hi,
>
> The docstring of directory-file-recursively in lisp/files.el is unclear
> about the include-directories optional argument. It currently reads
>
> "Optional argument INCLUDE-DIRECTORIES non-nil means also include
> in the output directories whose names match REGEXP."
>
> Perhaps this could be rewritten as
>
> "If optional argument INCLUDE-DIRECTORIES is non-nil, the returned list
> also includes directories whose names match REGEXP."

Or a more prompting style

"If INCLUDE-DIRECTORIES is non-nil, also include directories whose names
matches REGEXP in the returned list."

I think it is not necessary to repeat that the argument is optional, but
maybe that is standard.

?

Best regards
--
Tomas

Message #20 received at 40202 <at> debbugs.gnu.org (full text, mbox):

From: Arun Isaac <arunisaac <at> systemreboot.net>
To: Tomas Nordin <tomasn <at> posteo.net>, 40202 <at> debbugs.gnu.org
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Thu, 26 Mar 2020 01:08:20 +0530

[Message part 1 (text/plain, inline)]

> Or a more prompting style
>
> "If INCLUDE-DIRECTORIES is non-nil, also include directories whose names
> matches REGEXP in the returned list."

I did consider this style. But, it is slightly harder to parse. For
example, it is easy to misparse the sentence as "also include
directories (whose names match REGEXP in the returned list)" when the
correct parsing should be "also include (directories whose names match
REGEXP) in the returned list".

[signature.asc (application/pgp-signature, inline)]

Message #25 received at 40202-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arun Isaac <arunisaac <at> systemreboot.net>
Cc: larsi <at> gnus.org, tomasn <at> posteo.net, 40202-done <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Wed, 25 Mar 2020 21:57:16 +0200

> From: Arun Isaac <arunisaac <at> systemreboot.net>
> Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
> Date: Thu, 26 Mar 2020 01:08:20 +0530
> 
> > Or a more prompting style
> >
> > "If INCLUDE-DIRECTORIES is non-nil, also include directories whose names
> > matches REGEXP in the returned list."
> 
> I did consider this style. But, it is slightly harder to parse. For
> example, it is easy to misparse the sentence as "also include
> directories (whose names match REGEXP in the returned list)" when the
> correct parsing should be "also include (directories whose names match
> REGEXP) in the returned list".

IME, if some text causes parsing difficulties, it is best dropped
altogether, especially if it is redundant.  So that's what I did, see
the emacs-27 branch.

And with that, I'm closing this bug.  Thanks for pointing out the
ambiguity of the original text.

Message #28 received at 40202-done <at> debbugs.gnu.org (full text, mbox):

From: Arun Isaac <arunisaac <at> systemreboot.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, tomasn <at> posteo.net, 40202-done <at> debbugs.gnu.org
Subject: Re: bug#40202: directory-files-recursively docstring unclear about
 include-directories
Date: Thu, 26 Mar 2020 03:06:03 +0530

[Message part 1 (text/plain, inline)]

> IME, if some text causes parsing difficulties, it is best dropped
> altogether, especially if it is redundant.  So that's what I did, see
> the emacs-27 branch.

Thank you! The new docstring is very clear.

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.