Re: Wrong command option in the manual examples

[Chet Ramey]

On 9/25/19 2:11 PM, Ole Tange wrote:

> I think you are right. The goal is to emulate 'ls'.
> 
> As you can see from GNU Parallel's manual I would use printf instead:
> 
> printf '%s\0' * | parallel -0 mv {} destdir

This is the best option, with the usual caveat about having to change the
pattern if you have `dotglob' enabled.

Chet
-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/

Re: Wrong command option in the manual examples

[Ole Tange]

On Mon, Sep 23, 2019 at 3:53 PM Chet Ramey  wrote:
>
> On 9/23/19 5:29 AM, Ilkka Virta wrote:
> > On 22.9. 21:15, Chet Ramey wrote:
> >> On 9/20/19 10:24 PM, hk wrote:
> >>
> >>> Description:
> >>>  On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
> >>> Reference Manual. The manual uses `find' command to illustrate
> >>> possible use cases of `parallel' as examples. but the option `-depth'
> >>> does not accept any argument, I think it means `-maxdepth` option
> >>> instead.

I think you are right. The goal is to emulate 'ls'.

As you can see from GNU Parallel's manual I would use printf instead:

printf '%s\0' * | parallel -0 mv {} destdir

but I feel you are right that -depth should simply be replaced with -maxdepth.

> >> -depth n
> >>True if the depth of the file relative to the starting point of
> >>the traversal is n.
> >>
> >> It's not in POSIX, and maybe GNU find doesn't implement it.
> >
> > That seems to raise a question.
> >
> > Isn't Bash a GNU project? Would it be prudent to use other GNU tools in
> > examples, if standard POSIX features aren't sufficient?

I seem to recall when I became a GNU maintainer that it was a higher
priority to integrate nicely with other GNU tools than to integrate
with non-GNU tools. I cannot find the exact wording now, so it may
have changed.

I understood that such that in examples it would be encouraged to
prioritize GNU find over FreeBSD find, but that it would be fine to
include both. So it would go against my understanding of that if the
Bash manual promoted FreeBSD find over GNU find. This also strengthens
my belief that what is really meant is -maxdepth.

But if the GNU find people do not mind and FreeBSD find does not have
-maxdepth, then I would suggest simply using

printf '%s\0' *

instead. It is shorter and IMHO easier to understand.

> > I can see that
> > FreeBSD find has '-depth n' (as well the standard '-depth', somewhat
> > confusingly) but should the reader of the manual be assumed to know the
> > options supported by BSD utilities?

If I recall the guidelines correctly: No.


/Ole

Re: Wrong command option in the manual examples

[Robert Elz]

Date:Mon, 23 Sep 2019 14:12:27 -0400
From:Chet Ramey 
Message-ID:  <49989bf9-7c12-2670-de3f-20feead50...@case.edu>

  | It's in SVR2 (1984?), at least,

Thanks.

  | The SVR2 page implies that it was added to support cpio.

Yes .. the function of the option is fine - when used while making the
archive the files get listed (and therefore added) first, and the directory
that contains them after all the files, which means that when extracted
the files can be written to their directory before the directory's permissions
are seen and set, perhaps denying writing.

What's wrong with it is making what is a global option act like it is an
expression primitive.   If it worked as an expression operator, you should
be able to do
find . -name foo -depth -o -name bar -nodepth ...
but you can't, aside from there being no "nodepth" or anything equivalent,
the -depth option is set for the whole traversal, before the first
directory is read, it doesn't only turn on when the primitive is executed.

Find at the time had no options, so where they should have just
added one (or three) they instead did that "make it an operator" solution.

kre

Re: Wrong command option in the manual examples

[Chet Ramey]

On 9/23/19 1:24 PM, Robert Elz wrote:
> Date:Mon, 23 Sep 2019 10:59:43 -0400
> From:Greg Wooledge 
> Message-ID:  <20190923145943.gx28...@eeg.ccf.org>
> 
>   | But... there literally *is* a real standard for this.
> 
> Hmm, yes, you're right.   That suggests that -depth must be a System-V
> invention (POSIX wouldn't have added a spec for an undocumented internal
> operator from BSD...)

It's in SVR2 (1984?), at least, and POSIX-1003.2d11 (1991) has it, without
any mention of where it came from, so I assume POSIX picked it up from the
SVID. The SVR2 page implies that it was added to support cpio.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/

Re: Wrong command option in the manual examples

[Robert Elz]

Date:Mon, 23 Sep 2019 10:59:43 -0400
From:Greg Wooledge 
Message-ID:  <20190923145943.gx28...@eeg.ccf.org>

  | But... there literally *is* a real standard for this.

Hmm, yes, you're right.   That suggests that -depth must be a System-V
invention (POSIX wouldn't have added a spec for an undocumented internal
operator from BSD...)

I don't have any System-V (particularly not ancient) sources available
to check - I did verify that -depth is not in System-III though (or at
least is not documented in it.)

kre

Re: Wrong command option in the manual examples

[Robert Elz]

Date:Mon, 23 Sep 2019 16:36:59 +0200
From:Andreas Schwab 
Message-ID:  

  | According to https://www.freebsd.org/cgi/man.cgi, find -d already
  | appeared in 4.3BSD, and -depth is much newer.

I can believe that, I did not research the history, just what is in
the NetBSD man page (and code).   It looks as if both -d and -depth
appeared in 4.3Reno, with -depth undocumented other than as an implementation
technique for -d (which is kind of a weird way to do it) and much the
same explanation of why -depth is wrong as appears in BSD man pages to
this day...

That kind of suggests that -depth (the no arg version) was older, and
originated elsewhere (none of this is in 4.3Tahoe) but that isn't clear.
If I ever find my BSD sccs files I might (if I still remember this) take
a look and see if there are more clues to the origins.

(-xdev, which was replaced/augmented by -x in 4.3Reno was certainly older).

FreeBSD's -depth N is certainly newer.

None of this affects my opinion that using -depth (any form) in an
example isn't a good choice.

kre

Re: Wrong command option in the manual examples

[Greg Wooledge]

On Mon, Sep 23, 2019 at 09:02:47PM +0700, Robert Elz wrote:
> There is no real standard for this - NetBSD has deprecated the -depth
> operator (which never really was one) and replaced it by a -d option
> which makes much more sense (-depth never really was the right way to
> do it).  -depth (the old way) is still supported for compat with old
> scripts, but is only mentioned in doc in the STANDARDS section, as:

But... there literally *is* a real standard for this.



   -depth
  The primary shall always evaluate as true; it shall cause descent
  of the directory hierarchy to be done so that all entries in a
  directory are acted on before the directory itself. If a -depth
  primary is not specified, all entries in a directory shall be acted
  on after the directory itself. If any -depth primary is specified,
  it shall apply to the entire expression even if the -depth primary
  would not normally be evaluated.

If the POSIX standard isn't real enough, then I don't know what is.

Re: Wrong command option in the manual examples

[Andreas Schwab]

On Sep 23 2019, Robert Elz  wrote:

> Date:Mon, 23 Sep 2019 12:29:18 +0300
> From:Ilkka Virta 
> Message-ID:  <59cf49b0-1292-b752-4fe8-8928fd558...@iki.fi>
>
>   | (as well the standard '-depth', somewhat confusingly)
>
> There is no real standard for this - NetBSD has deprecated the -depth
> operator (which never really was one) and replaced it by a -d option
> which makes much more sense (-depth never really was the right way to
> do it).

According to https://www.freebsd.org/cgi/man.cgi, find -d already
appeared in 4.3BSD, and -depth is much newer.

Andreas.

-- 
Andreas Schwab, SUSE Labs, sch...@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: Wrong command option in the manual examples

[Robert Elz]

Date:Mon, 23 Sep 2019 12:29:18 +0300
From:Ilkka Virta 
Message-ID:  <59cf49b0-1292-b752-4fe8-8928fd558...@iki.fi>

  | (as well the standard '-depth', somewhat confusingly)

There is no real standard for this - NetBSD has deprecated the -depth
operator (which never really was one) and replaced it by a -d option
which makes much more sense (-depth never really was the right way to
do it).  -depth (the old way) is still supported for compat with old
scripts, but is only mentioned in doc in the STANDARDS section, as:

 Historically, the -d, -h, and -x options were implemented using the
 primaries "-depth", "-follow", and "-xdev".  These primaries always
 evaluated to true, and always took effect when the expression was parsed,
 before the file system traversal began.  As a result, some legal
 expressions could be confusing.  For example, in the expression "-print
 -or -depth", -print always evaluates to true, so the standard meaning of
 -or implies that -depth would never be evaluated, but that is not what
 happens; in fact, -depth takes effect immediately, without testing
 whether -print returns true or false.

What I think is the purpose of poor choice of an option, the FreeBSD -depth N
is done using -maxdepth and -mindepth in combination (using the same value).

(That is, to select a depth of exactly N, one requests a depth of no less
than N and no more than N (where N, if signed, has the usual meaning, of
course).

Either way (as "-depth N", or "-mindepth N -maxdepth N") this is an operator
that applies to each path element encountered, so makes sense to have as
an element of the find expression (unlike the old -depth which does not.)

I'd strongly suggest not using examples of anything using "-depth" - choose
some other example instead.

kre

Re: Wrong command option in the manual examples

[Chet Ramey]

On 9/23/19 5:29 AM, Ilkka Virta wrote:
> On 22.9. 21:15, Chet Ramey wrote:
>> On 9/20/19 10:24 PM, hk wrote:
>>
>>> Bash Version: 5.0
>>> Patch Level: 0
>>> Release Status: release
>>>
>>> Description:
>>>  On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
>>> Reference Manual. The manual uses `find' command to illustrate
>>> possible use cases of `parallel' as examples. but the option `-depth'
>>> does not accept any argument, I think it means `-maxdepth` option
>>> instead.
>>
>> -depth n
>>    True if the depth of the file relative to the starting point of
>>    the traversal is n.
>>
>> It's not in POSIX, and maybe GNU find doesn't implement it.
> 
> That seems to raise a question.
> 
> Isn't Bash a GNU project? Would it be prudent to use other GNU tools in
> examples, if standard POSIX features aren't sufficient? I can see that
> FreeBSD find has '-depth n' (as well the standard '-depth', somewhat
> confusingly) but should the reader of the manual be assumed to know the
> options supported by BSD utilities?

That's a good question. It's complicated by the fact that parallel is not
part of bash, and I included the parallel manual verbatim upon request. I
don't know what the author's intent was with the example, or if -maxdepth
would work. Let's see if we can loop Ole Tange, the parallel author, into
this discussion.

Chet
-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/

Re: Wrong command option in the manual examples

[Ilkka Virta]

On 22.9. 21:15, Chet Ramey wrote:

On 9/20/19 10:24 PM, hk wrote:


Bash Version: 5.0
Patch Level: 0
Release Status: release

Description:
 On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
Reference Manual. The manual uses `find' command to illustrate
possible use cases of `parallel' as examples. but the option `-depth'
does not accept any argument, I think it means `-maxdepth` option
instead.


-depth n
   True if the depth of the file relative to the starting point of
   the traversal is n.

It's not in POSIX, and maybe GNU find doesn't implement it.


That seems to raise a question.

Isn't Bash a GNU project? Would it be prudent to use other GNU tools in 
examples, if standard POSIX features aren't sufficient? I can see that 
FreeBSD find has '-depth n' (as well the standard '-depth', somewhat 
confusingly) but should the reader of the manual be assumed to know the 
options supported by BSD utilities?


--
Ilkka Virta / itvi...@iki.fi

Re: Wrong command option in the manual examples

[hk]

GNU-implemented `find' does have a `-depth' option and  a `-maxdepth'
option.
Directories[findutils]


On Mon, Sep 23, 2019 at 2:15 AM Chet Ramey  wrote:

> On 9/20/19 10:24 PM, hk wrote:
>
> > Bash Version: 5.0
> > Patch Level: 0
> > Release Status: release
> >
> > Description:
> > On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
> > Reference Manual. The manual uses `find' command to illustrate
> > possible use cases of `parallel' as examples. but the option `-depth'
> > does not accept any argument, I think it means `-maxdepth` option
> > instead.
>
> -depth n
>   True if the depth of the file relative to the starting point of
>   the traversal is n.
>
> It's not in POSIX, and maybe GNU find doesn't implement it.
>
> --
> ``The lyf so short, the craft so long to lerne.'' - Chaucer
>  ``Ars longa, vita brevis'' - Hippocrates
> Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/
>

Re: Wrong command option in the manual examples

[Chet Ramey]

On 9/20/19 10:24 PM, hk wrote:

> Bash Version: 5.0
> Patch Level: 0
> Release Status: release
> 
> Description:
> On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
> Reference Manual. The manual uses `find' command to illustrate
> possible use cases of `parallel' as examples. but the option `-depth'
> does not accept any argument, I think it means `-maxdepth` option
> instead.

-depth n
  True if the depth of the file relative to the starting point of
  the traversal is n.

It's not in POSIX, and maybe GNU find doesn't implement it.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/

Wrong command option in the manual examples

[hk]

Configuration Information [Automatically generated, do not change]:
Machine: x86_64
OS: linux-gnu
Compiler: gcc
Compilation CFLAGS: -g -O2 -Wno-parentheses -Wno-format-security
uname output: Linux hk 4.15.0-62-generic #69-Ubuntu SMP Wed Sep 4 20:55:53
UTC 2019 x86_64 x86_64 x86_64 GNU/Linux
Machine Type: x86_64-pc-linux-gnu

Bash Version: 5.0
Patch Level: 0
Release Status: release

Description:
On the section 3.2.6(GNU Parallel, page 16 in the pdf) of Bash
Reference Manual. The manual uses `find' command to illustrate
possible use cases of `parallel' as examples. but the option `-depth'
does not accept any argument, I think it means `-maxdepth` option
instead.

Repeat-By:
[Describe the sequence of events that causes the problem
to occur.]

Fix:
replace `-depth' with `-maxdepth'