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

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Arun Isaac

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 (497 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Arun Isaac <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Arun Isaac

>> 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 (497 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Arun Isaac <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Tomas Nordin-2
In reply to this post by Arun Isaac
Arun Isaac <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Arun Isaac <[hidden email]>
> Cc: Lars Ingebrigtsen <[hidden email]>, Eli Zaretskii <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Arun Isaac

> 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 (497 bytes) Download Attachment