bug#40202: directory-files-recursively docstring unclear about include-directories

bug#40202: directory-files-recursively docstring unclear about include-directories

[Arun Isaac]

[-- Attachment #1: Type: text/plain, Size: 442 bytes --]


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#40202: directory-files-recursively docstring unclear about include-directories

[Eli Zaretskii]

> From: Arun Isaac <arunisaac@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.

bug#40202: directory-files-recursively docstring unclear about include-directories

[Arun Isaac]

[-- Attachment #1: Type: text/plain, Size: 1428 bytes --]


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#40202: directory-files-recursively docstring unclear about include-directories

[Lars Ingebrigtsen]

Arun Isaac <arunisaac@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

bug#40202: directory-files-recursively docstring unclear about include-directories

[Tomas Nordin]

Arun Isaac <arunisaac@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

bug#40202: directory-files-recursively docstring unclear about include-directories

[Arun Isaac]

[-- Attachment #1: Type: text/plain, Size: 449 bytes --]


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#40202: directory-files-recursively docstring unclear about include-directories

[Eli Zaretskii]

> From: Arun Isaac <arunisaac@systemreboot.net>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Eli Zaretskii <eliz@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.

bug#40202: directory-files-recursively docstring unclear about include-directories

[Arun Isaac]

[-- Attachment #1: Type: text/plain, Size: 209 bytes --]


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]