From b9ddd2bca1032fccbb6435b1e176af6f7a7485df Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Sat, 19 Oct 2019 18:30:49 +0200
Subject: [PATCH] doc: enhance description of tests accepting numeric arguments
 in find.1

* find/find.1 (TESTS): Improve the description of tests accepting a
numeric argument that they match "less than, more than or exactly" the
given 'n', thus helping the user to remind to use '-n', '+n' or a bare
'n' (as decribed at the top).
* doc/find.texi (section find Expressions): Move section from chapter
"Introduction" to "Finding Files".  The description about the general
syntax of a find expression fits more naturally there, including the
already existing part about numeric arguments.
* NEWS: Mention the change.
Suggested in https://sv.gnu.org/bugs/?57025 .
---
 NEWS          |  2 ++
 doc/find.texi | 45 +++++++++++++++++++++++----------------------
 find/find.1   | 44 ++++++++++++++++++++++++++++++--------------
 3 files changed, 55 insertions(+), 36 deletions(-)

diff --git a/NEWS b/NEWS
index ac7bbda9..5f741934 100644
--- a/NEWS
+++ b/NEWS
@@ -21,6 +21,8 @@ FINDUTILS_4_3_3-1 back in 2007.
 
 #58205: find.1: clarify double dash '--' option
 
+#57025: doc: enhance description of tests accepting numeric arguments in find.1
+
 #54730: Add additional valuable example of find -quit
 
 #48135: Fix testsuite error on Hurd and BSD related to ln
diff --git a/doc/find.texi b/doc/find.texi
index 45b86fe2..4dde0156 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -144,7 +144,6 @@ check the GNU FTP site.
 @menu
 * Scope::
 * Overview::
-* find Expressions::
 @end menu
 
 @node Scope
@@ -278,6 +277,29 @@ word @samp{typedef}.
 xargs grep typedef < file-list
 @end example
 
+@node Finding Files
+@chapter Finding Files
+
+By default, @code{find} prints to the standard output the names of the
+files that match the given criteria.  @xref{Actions}, for how to get
+more information about the matching files.
+
+
+@menu
+* find Expressions::
+* Name::
+* Links::
+* Time::
+* Size::
+* Type::
+* Owner::
+* Mode Bits::
+* Contents::
+* Directories::
+* Filesystems::
+* Combining Primaries With Operators::
+@end menu
+
 @node find Expressions
 @section @code{find} Expressions
 
@@ -334,27 +356,6 @@ for less than @var{n},
 for exactly @var{n}.
 @end table
 
-@node Finding Files
-@chapter Finding Files
-
-By default, @code{find} prints to the standard output the names of the
-files that match the given criteria.  @xref{Actions}, for how to get
-more information about the matching files.
-
-
-@menu
-* Name::
-* Links::
-* Time::
-* Size::
-* Type::
-* Owner::
-* Mode Bits::
-* Contents::
-* Directories::
-* Filesystems::
-* Combining Primaries With Operators::
-@end menu
 
 @node Name
 @section Name
diff --git a/find/find.1 b/find/find.1
index 6bc3d1ac..45895158 100644
--- a/find/find.1
+++ b/find/find.1
@@ -601,7 +601,17 @@ system call fails for it), an error message is issued, and
 .B find
 exits with a nonzero status.
 .P
-Numeric arguments can be specified as
+A numeric argument \fIn\fR can be specified to tests (like
+.BR \-amin ,
+.BR \-mtime ,
+.BR \-gid ,
+.BR \-inum ,
+.BR \-links ,
+.BR \-size ,
+.BR \-uid
+and
+.BR \-used )
+as
 .IP \fI+n\fP
 for greater than
 .IR n ,
@@ -612,8 +622,11 @@ for less than
 for exactly
 .IR n .
 .
+.P
+Supported tests:
+
 .IP "\-amin \fIn\fR"
-File was last accessed \fIn\fR minutes ago.
+File was last accessed less than, more than or exactly \fIn\fR minutes ago.
 
 .IP "\-anewer \fIreference\fR"
 Time of the last access of the current file is more recent than that
@@ -626,7 +639,7 @@ option is in effect, then the time of the last data modification of the file
 it points to is always used.
 
 .IP "\-atime \fIn\fR"
-File was last accessed
+File was last accessed less than, more than or exactly
 .IR n *24
 hours ago.
 When find figures out how many 24-hour periods ago the file
@@ -638,7 +651,8 @@ a file has to have been accessed at least
 days ago.
 
 .IP "\-cmin \fIn\fR"
-File's status was last changed \fIn\fR minutes ago.
+File's status was last changed less than, more than or exactly \fIn\fR minutes
+ago.
 
 .IP "\-cnewer \fIreference\fR"
 Time of the last status change of the current file is more recent than that
@@ -651,7 +665,7 @@ option is in effect, then the time of the last data modification of the file
 it points to is always used.
 
 .IP "\-ctime \fIn\fR"
-File's status was last changed
+File's status was last changed less than, more than or exactly
 .IR n *24
 hours ago.
 See the comments for
@@ -694,7 +708,7 @@ is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K.  You can use
 with the %F directive to see the types of your filesystems.
 
 .IP "\-gid \fIn\fR"
-File's numeric group ID is
+File's numeric group ID is less than, more than or exactly
 .IR n .
 
 .IP "\-group \fIgname\fR"
@@ -721,7 +735,7 @@ patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo',
 The pattern `*foo*` will also match a file called '.foobar'.
 
 .IP "\-inum \fIn\fR"
-File has inode number
+File has inode number smaller than, greater than or exactly
 .IR n .
 It is normally easier to use the
 .B \-samefile
@@ -742,7 +756,7 @@ See \-ipath.  This alternative is less portable than
 .BR \-ipath .
 
 .IP "\-links \fIn\fR"
-File has \fIn\fR hard links.
+File has less than, more than or exactly \fIn\fR hard links.
 
 .IP "\-lname \fIpattern\fR"
 File is a symbolic link whose contents match shell pattern
@@ -756,10 +770,11 @@ option is in effect, this test returns false unless the symbolic link
 is broken.
 
 .IP "\-mmin \fIn\fR"
-File's data was last modified \fIn\fR minutes ago.
+File's data was last modified less than, more than or exactly \fIn\fR minutes
+ago.
 
 .IP "\-mtime \fIn\fR"
-File's data was last modified
+File's data was last modified less than, more than or exactly
 .IR n *24
 hours ago.
 See the comments for
@@ -961,8 +976,8 @@ When
 is in effect, this can include symbolic links.
 
 .IP "\-size \fIn\fR[cwbkMG]"
-File uses \fIn\fP units of space, rounding up.  The following suffixes
-can be used:
+File uses less than, more than or exactly \fIn\fP units of space, rounding up.
+The following suffixes can be used:
 .RS
 .IP `b'
 for 512-byte blocks (this is the default if no suffix is used)
@@ -1035,11 +1050,12 @@ door (Solaris)
 To search for more than one type at once, you can supply the combined list of
 type letters separated by a comma `,' (GNU extension).
 .IP "\-uid \fIn\fR"
-File's numeric user ID is
+File's numeric user ID is less than, more than or exactly
 .IR n .
 
 .IP "\-used \fIn\fR"
-File was last accessed \fIn\fR days after its status was last changed.
+File was last accessed less than, more than or exactly \fIn\fR days after its
+status was last changed.
 
 .IP "\-user \fIuname\fR"
 File is owned by user \fIuname\fR (numeric user ID allowed).
-- 
2.28.0

