bin/45381: several fixes to grammar, formatting, and descriptions in find(1)

["Greg A. Woods" <woods%planix.com@localhost>]

>Number:         45381
>Category:       bin
>Synopsis:       several fixes to grammar, spelling, formatting, and 
>descriptions in find(1)
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Sep 21 04:25:01 +0000 2011
>Originator:     Greg A. Woods
>Release:        netbsd-5
>Organization:
Planix, Inc.; Kelowna, BC; Canada
>Environment:
System: NetBSD
Architecture: 
Machine: 
>Description:

        There's some poor wording, poor formatting, and poor grammar, and
        poor spelling in find(1), notably:

        - the description of numeric parameters should be first and
          foremost, and it needs to be specific about the 'n'

        - the description of "-exec", and the formatting, is impossible
          to understand clearly

        - '+' and ';', and other characters that are to be input
          literally should be shown as such.

        - a few more examples would help!

        - some wording and formatting in the history section is poor


>How-To-Repeat:

>Fix:

        this diff is againt the version in netbsd-5, and I hope is
        mostly non-conflicting with more recent changes, though I expect
        there will be a few conflicts, but I need these changes for my
        NetBSD-5 builds and I'm not presently working on -current

        (it would really help users of release branches with submitting
        changes like this if NetBSD had a default "merge-from-current"
        policy for all fixes and all compatible features instead of
        requiring explicit pull-up requests for all release branch
        changes)


--- find.1      12 Apr 2010 10:33:13 -0700      1.66
+++ find.1      20 Sep 2011 20:48:26 -0700      
@@ -161,6 +161,7 @@
 .Pq Dq \&'
 and double
 .Pq Dq \&"
+.\" " for Emacs
 quotes, backslash
 .Pq Dq \e ,
 space, tab and newline characters.
@@ -179,6 +180,18 @@
 Does not list mount points to other file systems.
 .El
 .Sh PRIMARIES
+All primaries which take a numeric argument of
+.Ar n
+allow the number to be preceded by a plus sign
+.Pq Dq +
+or a minus sign
+.Pq Dq \- .
+A preceding plus sign means
+.Dq more than Ar n ,
+a preceding minus sign means
+.Dq less than Ar n ,
+and neither means
+.Dq exactly Ar n .
 .Bl -tag -width Ds
 .It Ic -amin Ar n
 True if the difference between the file last access time and the time
@@ -229,75 +242,92 @@
 .It Ic -empty
 True if the current file or directory is empty.
 .\" The ".sp" below is probably not the right way to get the desired effect.
-.It Ic -exec Ar utility Oo argument ... Oc No ;
+.It Ic -exec Ar utility Oo argument ... Oc Ic \;
 .sp -1l
-.It Ic -exec Ar utility Oo argument ... Oc No {} +
+.It Ic -exec Ar utility Oo argument ... Oc Ic {} Ic +
 Execute the specified
 .Ar utility
 with the specified arguments.
-The list of arguments is terminated by
+.Pp
+The list of arguments for
+.Ar utility
+is terminated by a lone
 .Dq Li \&;
 or
-.Dq Li \&+ .
-.Ar utility
-will be executed from the directory from which
-.Nm
-was executed.
+.Dq Li \&+
+character as a separate parameter.
 .Pp
-If terminated by a semicolon
-.Pq Dq \&; ,
-the
+If the list of arguments is terminated by a semicolon
+.Pq Dq Ic \&;
+then the
 .Ar utility
-is invoked once per path.
-If the string
-.Dq {}
-appears anywhere in the utility name or the arguments,
-it is replaced by the pathname of the current file.
-.Pp
-If terminated by a plus sign
-.Pq Dq \&+ ,
-the pathnames for which the
-primary is evaluated are aggregated into sets, and
+is invoked once per pathname.
+.Em If
+the string
+.Dq Ic {}
+appears anywhere in the utility name or the arguments
+then it is replaced by the pathname of the current file
+(but it need not appear, in which case the pathnames will not be given
+to the utility).
+Note the semicolon will have to be escaped on the shell command line in
+order to be passed as a parameter.
+.Pp
+If the list of arguments is terminated by a plus sign
+.Pq Dq Ic \&+
+then the pathnames for which the primary is evaluated are aggregated
+into sets, and
 .Ar utility
 will be invoked once per set, similar to
 .Xr xargs 1 .
-If any invocation exits with non-zero exit status, then
+In this case the parameter
+.Dq Ic {}
+must appear as the last item in the argument list, just before the
+.Dq Ic \&+
+parameter.
+Each set is limited to no more than 5,000 pathnames,
+and is also limited such that the total number of bytes in the argument
+list does not exceed
+.Dv ARG_MAX .
+.Pp
+The command specified by
+.Ar utility
+will be executed with its current working directory being the directory
+from which
+.Nm
+was executed.
+.Pp
+If any invocation of
+.Ar utility
+exits with non-zero exit status, then
 .Nm
 will eventually do so as well, but this does not cause
 .Nm
 to exit early.
-The string
-.Dq {}
-must appear, and must appear last.
-Each set is limitted to no more than 5,000 pathnames,
-and is also limitted such that the invokation of
-.Ar utility
-does not exceed
-.Dv ARG_MAX .
-.It Ic -execdir Ar utility Oo argument ... Oc No ;
+.\"
+.It Ic -execdir Ar utility Oo argument ... Oc Ic \;
 The
 .Ic -execdir
 primary is similar to the semicolon-terminated
-.Pq Dq \&;
+.Pq Dq Ic \&;
 variant of the
 .Ic -exec
 primary, with the exception that
 .Ar utility
 will be executed from the directory that holds
 the current file.
-The filename substituted for the string
-.Dq {}
-is not qualified.
+Only the base filename is substituted for the string
+.Dq Ic {} .
 Set aggregation
 .Pq Do \&+ Dc termination
 is not supported.
-.It Ic -exit Op Ar n
+.It Ic -exit Op Ar x
 This primary causes
 .Nm
 to stop traversing the filesystem and exit immediately if a
 previous condition was met.
-If no value is specified, the exit value will be 0, else
-.Ar n .
+If no value is specified, the exit value will be 0, otherwise it will be
+the numeric value
+.Ar x .
 Note that other primaries will be evaluated and acted upon before exiting.
 .It Ic -false
 This primary always evaluates to false.
@@ -312,7 +342,7 @@
 If
 .Ar flags
 are preceded by a dash
-.Pq Dq - ,
+.Pq Dq Ic \- ,
 this primary evaluates to true
 if at least all of the bits in
 .Ar flags
@@ -422,7 +452,7 @@
 was started, rounded up to the next full 24-hour period, is
 .Ar n
 24-hour periods.
-.It Ic -ok Ar utility Oo argument ... Oc No ;
+.It Ic -ok Ar utility Oo argument ... Oc Ic ;
 The
 .Ic -ok
 primary is similar to the semicolon-terminated
@@ -436,7 +466,7 @@
 If the response is other than
 .Dq y ,
 the command is not executed and the
-.Ar -ok
+.Ic -ok
 primary evaluates to false.
 Set aggregation
 .Pq Do \&+ Dc termination
@@ -507,13 +537,13 @@
 of the file's mode bits participate
 in the comparison.
 If the mode is preceded by a dash
-.Pq Dq - ,
+.Pq Dq Ic \- ,
 this primary evaluates to true
 if at least all of the bits in the mode are set in the file's mode bits.
 If the mode is not preceded by a dash, this primary evaluates to true if
 the bits in the mode exactly match the file's mode bits.
 Note, the first character of a symbolic mode may not be a dash
-.Pq Dq - .
+.Pq Dq Ic \- .
 .It Ic -print
 This primary always evaluates to true.
 It prints the pathname of the current file to standard output, followed
@@ -533,7 +563,7 @@
 .It Ic -print0
 This primary always evaluates to true.
 It prints the pathname of the current file to standard output, followed
-by a null character.
+by a NUL character.
 .It Ic -printx
 This primary always evaluates to true.
 It prints the pathname of the current file to standard output,
@@ -565,7 +595,7 @@
 If
 .Ar n
 is followed by a
-.Dq c ,
+.Dq Ic c ,
 then the primary is true if the file's size is
 .Ar n
 bytes.
@@ -609,18 +639,6 @@
 .Xr stat 2
 S5.6.2 [POSIX.1]).
 .El
-.Pp
-All primaries which take a numeric argument allow the number to be
-preceded by a plus sign
-.Pq Dq +
-or a minus sign
-.Pq Dq \- .
-A preceding plus sign means
-.Dq more than n ,
-a preceding minus sign means
-.Dq less than n ,
-and neither means
-.Dq exactly n .
 .Sh OPERATORS
 The primaries may be combined using the following operators.
 The operators are listed in order of decreasing precedence.
@@ -668,40 +686,52 @@
 .Nm
 utility normally exits 0 on success, and exits with 1 under certain
 internal error conditions.
-If any invokations of
-.Dq Ic -exec Ar ... No +
+If any invocations of
+.Dq Ic -exec Ar ... Ic +
 primaries return non-zero exit-status, then
 .Nm
 will do so as well.
 .Sh EXAMPLES
 The following examples are shown as given to the shell:
 .Bl -tag -width findx
-.It Li "find  /  \e!  -name  \*q*.c\*q  -print"
+.It Li "find  /  \e!  -name  \*q*.c\*q  \-print"
 Print out a list of all the files whose names do not end in
 .Dq \&.c .
-.It Li "find  /  -newer  ttt  -user  wnj  -print"
+.It Li "find  /  \-newer  ttt  \-user  wnj  \-print"
 Print out a list of all the files owned by user
 .Dq wnj
 that are newer than the file
 .Dq ttt .
-.It Li "find  /  \e!  \e(  -newer  ttt  -user  wnj  \e)  -print"
+.It Li "find  .  \-type  f  \-mmin  \-30  \-print  \-or  \-mindepth  1  
\-prune"
+Print out a list of all the files in the current directory that are
+newer than 30 minutes.
+.It Li "find  .  \-type  f  \-atime  +10  \-mindepth  2  \-print"
+Print out a list of all the files in any sub-directories that have not
+been accessed in the past ten days.
+.It Li "find  .  \-mtime  +90  \-exec  rm  \-i  {}  +  \-or  \-mindepth  1  
\-prune"
+Interactively remove all of the files in the current directory that have
+not been modified in 90 days.
+.It Li "find  .  \-type  f  \-mtime  +90  \-ok  mv  {}  {}.old  \e;"
+Interactively rename all of the files in the current directory and all
+sub-directories that have not been modified in 90 days.
+.It Li "find  /  \e!  \e(  \-newer  ttt  \-user  wnj  \e)  \-print"
 Print out a list of all the files which are not both newer than
 .Dq ttt
 and owned by
 .Dq wnj .
-.It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -print"
+.It Li "find  /  \e(  \-newer  ttt  \-or  \-user  wnj  \e)  \-print"
 Print out a list of all the files that are either owned by
 .Dq wnj
 or that are newer than
 .Dq ttt .
-.It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -exit 1"
+.It Li "find  /  \e(  \-newer  ttt  \-or  \-user  wnj  \e)  \-exit  1"
 Return immediately with a value of 1 if any files are found that are either
 owned by
 .Dq wnj
 or that are newer than
 .Dq ttt ,
 but do not print them.
-.It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -ls -exit 1"
+.It Li "find  /  \e(  \-newer  ttt  \-or  \-user  wnj  \e)  \-ls  \-exit  1"
 Same as above, but list the first file matching the criteria before exiting
 with a value of 1.
 .El
@@ -757,41 +787,45 @@
 and
 .Fl x
 options were implemented using the primaries
-.Dq -depth ,
-.Dq -follow ,
+.Dq Ic -depth ,
+.Dq Ic -follow ,
 and
-.Dq -xdev .
+.Dq Ic -xdev .
 These primaries always evaluated to true.
 As they were really global variables that took effect before the traversal
 began, some legal expressions could have unexpected results.
 An example is the expression
-.Dq -print -o -depth .
-As -print always evaluates to true, the standard order of evaluation
-implies that -depth would never be evaluated.
+.Dq Ic -print Ic -o Ic -depth .
+As
+.Ic -print
+always evaluates to true, the standard order of evaluation
+implies that
+.Ic -depth
+would never be evaluated.
 This is not the case.
 .Pp
-The operator
-.Dq -or
+Historically, the operator
+.Dq Ic -or
 was implemented as
-.Dq -o ,
+.Dq Ic -o ,
 and the operator
-.Dq -and
+.Dq Ic -and
 was implemented as
-.Dq -a .
+.Dq Ic -a .
 .Pp
 Historic implementations of the
-.Ic -exec
+.Dq Ic -exec
 and
-.Ic -ok
+.Dq Ic -ok
 primaries did not replace the string
-.Dq {}
+.Dq Ic {}
 in the utility name or the
-utility arguments if it had preceding or following non-whitespace characters.
+utility arguments if it was not surrounded by whitespace characters.
 This version replaces it no matter where in the utility name or arguments
 it appears.
 .Pp
 Support for
-.Dq Ic -exec Ar ... No +
+.Dq Ic -exec Ar ... Ic +
 is consistent with
 .Em IEEE PASC Interpretation 1003.2 #210 ,
 though the feature originated in