bug#23429: 25.0.90; `dired-do-find-regexp' doc string

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Drew Adams]

  "Find all matches for REGEXP in all marked files, recursively."

What does it mean to find matches in a particular marked file,
_recursively_?  This seems to be a nonsense description.

If what you mean is that the marked files in a marked _subdirectory_
are searched, and so on for its marked subdirs, recursively - then
say so.

If you don't mean something like that then I cannot imagine what this
means.  How can a _file_ (marked or not) be searched recursively?


In GNU Emacs 25.0.90.4 (i686-w64-mingw32)
 of 2016-03-20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-w64-mingw32 --without-dbus
 --without-compress-install CFLAGS=-static'

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Dmitry Gutov]

On 05/02/2016 08:57 PM, Drew Adams wrote:

> If what you mean is that the marked files in a marked _subdirectory_
> are searched, and so on for its marked subdirs, recursively - then
> say so.

Care to propose an exact wording?

> If you don't mean something like that then I cannot imagine what this
> means.  How can a _file_ (marked or not) be searched recursively?

A file can be a directory, in Emacs and in general Unix parlance.

Those marked files that are, are searched recursively. The regular files 
are searched, period.

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Drew Adams]

> > If what you mean is that the marked files in a marked _subdirectory_
> > are searched, and so on for its marked subdirs, recursively - then
> > say so.
> 
> Care to propose an exact wording?

Nope. Dunno what the command does, and don't have the time to
study the code more.

> > If you don't mean something like that then I cannot imagine what this
> > means.  How can a _file_ (marked or not) be searched recursively?
> 
> A file can be a directory, in Emacs and in general Unix parlance.

You mean that a directory is, or can be, a file.  But it is a
particular kind of file.  If you mean a directory then say a
directory.

And even for a directory, if regarded as a file it cannot be
searched recursively.  The _contents_ of a directory can be
searched, and the contents of its subdirectories can be searched,
and so on.

> Those marked files that are, are searched recursively. The regular files
> are searched, period.

  Search marked files, including marked subdirs.  Act recursively
  on marked subdirs.

But you need to specify whether ALL files and ALL subdirs in
a marked subdir are acted on, or just the marked files and 
marked subdirs in a marked subdir.

Here's one possibility (from Dired+):

  The files searched are those that are marked in the current
  Dired buffer.  Marked subdirectories are handled recursively
  in the same way.

Dunno whether that is the behavior you have, but you see that
there are several possibilities.

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Eli Zaretskii]

> Date: Mon, 2 May 2016 11:26:11 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> But you need to specify whether ALL files and ALL subdirs in
> a marked subdir are acted on, or just the marked files and 
> marked subdirs in a marked subdir.
> 
> Here's one possibility (from Dired+):
> 
>   The files searched are those that are marked in the current
>   Dired buffer.  Marked subdirectories are handled recursively
>   in the same way.
> 
> Dunno whether that is the behavior you have, but you see that
> there are several possibilities.

Fixed, thanks.

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Dmitry Gutov]

On 05/02/2016 10:58 PM, Eli Zaretskii wrote:

> Fixed, thanks.

Thanks, Eli.

Should the docstrings mention that some files and subdirectories do get 
ignored, according to vc-directory-exclusion-list and 
grep-find-ignored-files?

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Drew Adams]

> Should the docstrings mention that some files and subdirectories do get
> ignored, according to vc-directory-exclusion-list and
> grep-find-ignored-files?

I'm not Eli, but yes.

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Dmitry Gutov]

On 05/02/2016 11:14 PM, Drew Adams wrote:
>> Should the docstrings mention that some files and subdirectories do get
>> ignored, according to vc-directory-exclusion-list and
>> grep-find-ignored-files?
>
> I'm not Eli, but yes.

Would you like to propose the wording?

Should both dired-do-find-regexp and dired-do-find-regexp-and-replace's 
docstrings contain the same sentences for that information?

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Drew Adams]

> >> Should the docstrings mention that some files and subdirectories do get
> >> ignored, according to vc-directory-exclusion-list and
> >> grep-find-ignored-files?
> >
> > I'm not Eli, but yes.
> 
> Would you like to propose the wording?

Presumably something like this (?).

 Files with names matching the values of `vc-directory-exclusion-list'
 or `grep-find-ignored-files' are not searched.

> Should both dired-do-find-regexp and dired-do-find-regexp-and-replace's
> docstrings contain the same sentences for that information?

If the meaning/behavior is the same, why not?

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Dmitry Gutov]

On 05/02/2016 11:58 PM, Drew Adams wrote:

> Presumably something like this (?).
>
>  Files with names matching the values of `vc-directory-exclusion-list'
>  or `grep-find-ignored-files' are not searched.

Do you not mind that `vc-directory-exclusion-list' enumerates directory 
names, and not regular files?

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Drew Adams]

> > Presumably something like this (?).
> >
> >  Files with names matching the values of `vc-directory-exclusion-list'
> >  or `grep-find-ignored-files' are not searched.
> 
> Do you not mind that `vc-directory-exclusion-list' enumerates directory
> names, and not regular files?

I said "presumably" because I was presuming that the regexp matched file names. Adjust the language accordingly, if it is somehow enough to match a directory name (?).

bug#23429: 25.0.90; `dired-do-find-regexp' doc string

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 2 May 2016 23:11:52 +0300
> 
> On 05/02/2016 10:58 PM, Eli Zaretskii wrote:
> 
> > Fixed, thanks.
> 
> Thanks, Eli.
> 
> Should the docstrings mention that some files and subdirectories do get 
> ignored, according to vc-directory-exclusion-list and 
> grep-find-ignored-files?

Added, thanks.