Bug 168885

Summary: man page for find(1) fails to describe the -depth option
Product: Documentation Reporter: Ronald F. Guilmette <rfg>
Component: Books & ArticlesAssignee: Isabell Long <issyl0>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Ronald F. Guilmette 2012-06-09 06:30:11 UTC 
The man page for find(1) contains no useful information about the -depth
and/or -d options.

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.
How-To-Repeat: 
man 1 find
Comment 1 Isabell Long freebsd_committer freebsd_triage 2012-06-09 12:04:27 UTC 
State Changed
From-To: open->feedback

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,
Comment 2 Isabell Long freebsd_committer freebsd_triage 2012-06-09 12:04:27 UTC 
Responsible Changed
From-To: freebsd-doc->issyl0

Taking this one.
Comment 3 Ronald F. Guilmette 2012-06-09 12:29:31 UTC 
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.
Comment 4 dfilter service freebsd_committer freebsd_triage 2012-06-10 23:15:16 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"
Comment 5 Isabell Long freebsd_committer freebsd_triage 2012-06-10 23:19:48 UTC 
State Changed
From-To: feedback->closed

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!
Comment 6 dfilter service freebsd_committer freebsd_triage 2012-06-13 22:53:52 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"
Comment 7 dfilter service freebsd_committer freebsd_triage 2012-06-20 23:21:12 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"