unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#40202: directory-files-recursively docstring unclear about include-directories
@ 2020-03-23 21:16 Arun Isaac
  2020-03-24  3:25 ` Eli Zaretskii
  2020-03-25 17:20 ` Tomas Nordin
  0 siblings, 2 replies; 8+ messages in thread
From: Arun Isaac @ 2020-03-23 21:16 UTC (permalink / raw)
  To: 40202

[-- 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 --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-23 21:16 bug#40202: directory-files-recursively docstring unclear about include-directories Arun Isaac
@ 2020-03-24  3:25 ` Eli Zaretskii
  2020-03-24  8:22   ` Arun Isaac
  2020-03-25 17:20 ` Tomas Nordin
  1 sibling, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2020-03-24  3:25 UTC (permalink / raw)
  To: Arun Isaac; +Cc: 40202

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-24  3:25 ` Eli Zaretskii
@ 2020-03-24  8:22   ` Arun Isaac
  2020-03-24 21:23     ` Lars Ingebrigtsen
  0 siblings, 1 reply; 8+ messages in thread
From: Arun Isaac @ 2020-03-24  8:22 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 40202

[-- 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 --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-24  8:22   ` Arun Isaac
@ 2020-03-24 21:23     ` Lars Ingebrigtsen
  0 siblings, 0 replies; 8+ messages in thread
From: Lars Ingebrigtsen @ 2020-03-24 21:23 UTC (permalink / raw)
  To: Arun Isaac; +Cc: 40202

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-23 21:16 bug#40202: directory-files-recursively docstring unclear about include-directories Arun Isaac
  2020-03-24  3:25 ` Eli Zaretskii
@ 2020-03-25 17:20 ` Tomas Nordin
  2020-03-25 19:38   ` Arun Isaac
  1 sibling, 1 reply; 8+ messages in thread
From: Tomas Nordin @ 2020-03-25 17:20 UTC (permalink / raw)
  To: Arun Isaac, 40202

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-25 17:20 ` Tomas Nordin
@ 2020-03-25 19:38   ` Arun Isaac
  2020-03-25 19:57     ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Arun Isaac @ 2020-03-25 19:38 UTC (permalink / raw)
  To: Tomas Nordin, 40202; +Cc: Lars Ingebrigtsen

[-- 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 --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-25 19:38   ` Arun Isaac
@ 2020-03-25 19:57     ` Eli Zaretskii
  2020-03-25 21:36       ` Arun Isaac
  0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2020-03-25 19:57 UTC (permalink / raw)
  To: Arun Isaac; +Cc: larsi, tomasn, 40202-done

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#40202: directory-files-recursively docstring unclear about include-directories
  2020-03-25 19:57     ` Eli Zaretskii
@ 2020-03-25 21:36       ` Arun Isaac
  0 siblings, 0 replies; 8+ messages in thread
From: Arun Isaac @ 2020-03-25 21:36 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, tomasn, 40202-done

[-- 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 --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2020-03-25 21:36 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-03-23 21:16 bug#40202: directory-files-recursively docstring unclear about include-directories Arun Isaac
2020-03-24  3:25 ` Eli Zaretskii
2020-03-24  8:22   ` Arun Isaac
2020-03-24 21:23     ` Lars Ingebrigtsen
2020-03-25 17:20 ` Tomas Nordin
2020-03-25 19:38   ` Arun Isaac
2020-03-25 19:57     ` Eli Zaretskii
2020-03-25 21:36       ` Arun Isaac

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).