From rfg@tristatelogic.com  Sat Jun  9 05:21:24 2012
Return-Path: <rfg@tristatelogic.com>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 8BCEC106564A
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  9 Jun 2012 05:21:24 +0000 (UTC)
	(envelope-from rfg@tristatelogic.com)
Received: from outgoing.tristatelogic.com (segfault.tristatelogic.com [69.62.255.118])
	by mx1.freebsd.org (Postfix) with ESMTP id 6A9C38FC14
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  9 Jun 2012 05:21:23 +0000 (UTC)
Received: by segfault.tristatelogic.com (Postfix, from userid 1237)
	id D29F75081B; Fri,  8 Jun 2012 22:21:22 -0700 (PDT)
Message-Id: <20120609052122.D29F75081B@segfault.tristatelogic.com>
Date: Fri,  8 Jun 2012 22:21:22 -0700 (PDT)
From: Ronald F.Guilmette <rfg@tristatelogic.com>
Reply-To: Ronald F.Guilmette <rfg@tristatelogic.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: man page for find(1) fails to describe the -depth option
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         168885
>Category:       docs
>Synopsis:       man page for find(1) fails to describe the -depth option
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    issyl0
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jun 09 05:30:11 UTC 2012
>Closed-Date:    Sun Jun 10 22:19:50 UTC 2012
>Last-Modified:  Wed Jun 20 22:30:12 UTC 2012
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 8.3-RELEASE amd64
>Organization:
entropy
>Environment:

8.3-RELEASE amd64

>Description:

The man page for find(1) contains no useful information about the -depth
and/or -d options.

>How-To-Repeat:

man 1 find

>Fix:

I could include here a direct quote from my old SVR4 hardcopy set of system
man pages, describing the -depth option, but then if FreeBSD used that, SCO
or some other knuckleheads would probably sue.  So I guess the maintainer
of the man page will just have to do the best he/she can.
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->feedback 
State-Changed-By: issyl0 
State-Changed-When: Sat Jun 9 11:04:27 UTC 2012 
State-Changed-Why:  
To submitter: 

I'm not sure what exactly you mean.  This is the relevant 
man page from 8.3 - the version of FreeBSD you reported to 
be using - and the -d option is documented: 

-d      Cause find to perform a depth-first traversal, i.e., directories 
are visited in post-order and all entries in a directory will be 
acted on before the directory itself.  By default, find visits 
directories in pre-order, i.e., before their contents.  Note, the 
default is not a breadth-first traversal. 

This option is equivalent to the -depth primary of IEEE Std 
1003.1-2001 (``POSIX.1'').  The -d option can be useful when find 
is used with cpio(1) to process files that are contained in 
directories with unusual permissions.  It ensures that you have 
write permission while you are placing files in a directory, then 
sets the directory's permissions as the last thing. 

If you feel this could be clarified in some way, please let me know. 

Thanks, 

Isabell. 



Responsible-Changed-From-To: freebsd-doc->issyl0 
Responsible-Changed-By: issyl0 
Responsible-Changed-When: Sat Jun 9 11:04:27 UTC 2012 
Responsible-Changed-Why:  
Taking this one. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=168885 

From: "Ronald F. Guilmette" <rfg@tristatelogic.com>
To: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org
Cc:  
Subject: Re: docs/168885: man page for find(1) fails to describe the -depth option
Date: Sat, 09 Jun 2012 04:29:31 -0700

 Regarding this PR:
 
 http://www.freebsd.org/cgi/query-pr.cgi?pr=168885
 
 I noticed after I had filed it that actually, the -d option for find(1) is
 ``documented'' (for some value of ``documented'') in _two_ different locations
 within the find(1) man page, i.e. under the DESCRIPTION heading, and also under
 the PRIMARIES heading.
 
 In the first location, a full and complete description of the function of the
 -d option is in fact given.  However in the second location, virtually nothing
 is said about the functionality of -d, and there isn't even a reference
 telling the reader to look for documentation of the -d option higher up
 within the man page.
State-Changed-From-To: feedback->closed 
State-Changed-By: issyl0 
State-Changed-When: Sun Jun 10 22:19:48 UTC 2012 
State-Changed-Why:  
This has now been fixed in the main development branch and will be 
merged with earlier versions of FreeBSD in a few days.  Thanks for your 
report! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=168885 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/168885: commit references a PR
Date: Sun, 10 Jun 2012 22:15:16 +0000 (UTC)

 Author: issyl0 (doc committer)
 Date: Sun Jun 10 22:14:52 2012
 New Revision: 236860
 URL: http://svn.freebsd.org/changeset/base/236860
 
 Log:
   Add more description and clarification about the -depth and -d options in
   both places where they are mentioned in find(1).
   
   Discussed with:	dougb
   PR:		docs/168885
   Reported by:	Ronald F. Guilmette (rfg at tristatelogic dot com)
   Approved by:	gabor (mentor)
   MFC after:	3 days
 
 Modified:
   head/usr.bin/find/find.1
 
 Modified: head/usr.bin/find/find.1
 ==============================================================================
 --- head/usr.bin/find/find.1	Sun Jun 10 20:24:01 2012	(r236859)
 +++ head/usr.bin/find/find.1	Sun Jun 10 22:14:52 2012	(r236860)
 @@ -136,7 +136,7 @@ Note, the default is
  .Em not
  a breadth-first traversal.
  .Pp
 -This option is equivalent to the
 +This option is the BSD-specific equivalent of the
  .Ic -depth
  primary of
  .St -p1003.1-2001 .
 @@ -301,7 +301,7 @@ Please refer to the
  .Ic -atime
  primary description for information on supported time units.
  .It Ic -d
 -Same as
 +Non-portable, BSD-specific version of
  .Ic depth .
  GNU find implements this as a primary in mistaken emulation of
  .Fx
 @@ -325,9 +325,10 @@ primary will fail to delete a directory 
  Following symlinks is incompatible with this option.
  .It Ic -depth
  Always true;
 -same as the
 +same as the non-portable
  .Fl d
 -option.
 +option.  Refer to the primary description of
 +.Ic -depth for full information.
  .It Ic -depth Ar n
  True if the depth of the file relative to the starting point of the traversal
  is
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/168885: commit references a PR
Date: Wed, 13 Jun 2012 21:53:52 +0000 (UTC)

 Author: jilles
 Date: Wed Jun 13 21:53:40 2012
 New Revision: 237035
 URL: http://svn.freebsd.org/changeset/base/237035
 
 Log:
   find(1): Move description of -d option to -depth primary.
   
   The nullary -depth primary is standard and the -d option provides little
   advantage.
   
   PR:		docs/168885
   MFC after:	1 week
 
 Modified:
   head/usr.bin/find/find.1
 
 Modified: head/usr.bin/find/find.1
 ==============================================================================
 --- head/usr.bin/find/find.1	Wed Jun 13 21:38:07 2012	(r237034)
 +++ head/usr.bin/find/find.1	Wed Jun 13 21:53:40 2012	(r237035)
 @@ -31,7 +31,7 @@
  .\"	@(#)find.1	8.7 (Berkeley) 5/9/95
  .\" $FreeBSD$
  .\"
 -.Dd May 6, 2012
 +.Dd June 13, 2012
  .Dt FIND 1
  .Os
  .Sh NAME
 @@ -126,36 +126,15 @@ as an effective alternative.
  .It Fl d
  Cause
  .Nm
 -to perform a depth-first traversal, i.e., directories
 -are visited in post-order and all entries in a directory will be acted
 -on before the directory itself.
 -By default,
 -.Nm
 -visits directories in pre-order, i.e., before their contents.
 -Note, the default is
 -.Em not
 -a breadth-first traversal.
 +to perform a depth-first traversal.
  .Pp
 -This option is the BSD-specific equivalent of the
 +This option is a BSD-specific equivalent of the
  .Ic -depth
 -primary of
 +primary specified by
  .St -p1003.1-2001 .
 -The
 -.Fl d
 -option
 -can be useful when
 -.Nm
 -is used with
 -.Xr cpio 1
 -to process files that are contained in directories with unusual permissions.
 -It ensures that you have write permission while you are placing files in a
 -directory, then sets the directory's permissions as the last thing.
 -.It Fl f
 -Specify a file hierarchy for
 -.Nm
 -to traverse.
 -File hierarchies may also be specified as the operands immediately
 -following the options.
 +Refer to its description under
 +.Sx PRIMARIES
 +for more information.
  .It Fl s
  Cause
  .Nm
 @@ -327,8 +306,29 @@ Following symlinks is incompatible with 
  Always true;
  same as the non-portable
  .Fl d
 -option.  Refer to the primary description of
 -.Ic -depth for full information.
 +option.
 +Cause
 +.Nm
 +to perform a depth-first traversal, i.e., directories
 +are visited in post-order and all entries in a directory will be acted
 +on before the directory itself.
 +By default,
 +.Nm
 +visits directories in pre-order, i.e., before their contents.
 +Note, the default is
 +.Em not
 +a breadth-first traversal.
 +.Pp
 +The
 +.Ic -depth
 +primary
 +can be useful when
 +.Nm
 +is used with
 +.Xr cpio 1
 +to process files that are contained in directories with unusual permissions.
 +It ensures that you have write permission while you are placing files in a
 +directory, then sets the directory's permissions as the last thing.
  .It Ic -depth Ar n
  True if the depth of the file relative to the starting point of the traversal
  is
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/168885: commit references a PR
Date: Wed, 20 Jun 2012 22:21:12 +0000 (UTC)

 Author: jilles
 Date: Wed Jun 20 22:21:02 2012
 New Revision: 237345
 URL: http://svn.freebsd.org/changeset/base/237345
 
 Log:
   MFC r236860,r237035: find(1): Extend and move description of -d option to
   -depth primary.
   
   The nullary -depth primary is standard and the -d option provides little
   advantage.
   
   Commit r236860 originally by issyl0.
   
   PR:		docs/168885
 
 Modified:
   stable/9/usr.bin/find/find.1
 Directory Properties:
   stable/9/usr.bin/find/   (props changed)
 
 Modified: stable/9/usr.bin/find/find.1
 ==============================================================================
 --- stable/9/usr.bin/find/find.1	Wed Jun 20 21:38:16 2012	(r237344)
 +++ stable/9/usr.bin/find/find.1	Wed Jun 20 22:21:02 2012	(r237345)
 @@ -31,7 +31,7 @@
  .\"	@(#)find.1	8.7 (Berkeley) 5/9/95
  .\" $FreeBSD$
  .\"
 -.Dd March 17, 2010
 +.Dd June 13, 2012
  .Dt FIND 1
  .Os
  .Sh NAME
 @@ -126,36 +126,15 @@ as an effective alternative.
  .It Fl d
  Cause
  .Nm
 -to perform a depth-first traversal, i.e., directories
 -are visited in post-order and all entries in a directory will be acted
 -on before the directory itself.
 -By default,
 -.Nm
 -visits directories in pre-order, i.e., before their contents.
 -Note, the default is
 -.Em not
 -a breadth-first traversal.
 +to perform a depth-first traversal.
  .Pp
 -This option is equivalent to the
 +This option is a BSD-specific equivalent of the
  .Ic -depth
 -primary of
 +primary specified by
  .St -p1003.1-2001 .
 -The
 -.Fl d
 -option
 -can be useful when
 -.Nm
 -is used with
 -.Xr cpio 1
 -to process files that are contained in directories with unusual permissions.
 -It ensures that you have write permission while you are placing files in a
 -directory, then sets the directory's permissions as the last thing.
 -.It Fl f
 -Specify a file hierarchy for
 -.Nm
 -to traverse.
 -File hierarchies may also be specified as the operands immediately
 -following the options.
 +Refer to its description under
 +.Sx PRIMARIES
 +for more information.
  .It Fl s
  Cause
  .Nm
 @@ -302,7 +281,7 @@ Please refer to the
  .Ic -atime
  primary description for information on supported time units.
  .It Ic -d
 -Same as
 +Non-portable, BSD-specific version of
  .Ic depth .
  GNU find implements this as a primary in mistaken emulation of
  .Fx
 @@ -323,9 +302,31 @@ Depth-first traversal processing is impl
  Following symlinks is incompatible with this option.
  .It Ic -depth
  Always true;
 -same as the
 +same as the non-portable
  .Fl d
  option.
 +Cause
 +.Nm
 +to perform a depth-first traversal, i.e., directories
 +are visited in post-order and all entries in a directory will be acted
 +on before the directory itself.
 +By default,
 +.Nm
 +visits directories in pre-order, i.e., before their contents.
 +Note, the default is
 +.Em not
 +a breadth-first traversal.
 +.Pp
 +The
 +.Ic -depth
 +primary
 +can be useful when
 +.Nm
 +is used with
 +.Xr cpio 1
 +to process files that are contained in directories with unusual permissions.
 +It ensures that you have write permission while you are placing files in a
 +directory, then sets the directory's permissions as the last thing.
  .It Ic -depth Ar n
  True if the depth of the file relative to the starting point of the traversal
  is
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
