Fix Savannah bug 54730: additional examples for -quit.

* doc/find.texi (-quit): add another example.
* find/find.1 (-quit): add another example.
(-exec): Point out that -exec my-command {} + -quit
may not result in my-command being run.
(EXAMPLES): add an example for -quit.
* NEWS: mention this change.

NEWS

@@ -4,6 +4,8 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
 
 ** Bug Fixes
 
+#54730: Add additional valuable example of find -quit
+
 #48135: Fix testsuite error on Hurd and BSD related to ln
 
 * Major changes in release 4.7.0, 2019-08-29

doc/find.texi

@@ -1410,11 +1410,18 @@ Exit immediately (with return value zero if no errors have occurred).
 This is different to @samp{-prune} because @samp{-prune} only applies
 to the contents of pruned directories, while @samp{-quit} simply makes
 @code{find} stop immediately.  No child processes will be left
-running, but no more files specified on the command line will be
-processed.  For example, @code{find /tmp/foo /tmp/bar -print -quit}
-will print only @samp{/tmp/foo}.  Any command lines which have been
-built by @samp{-exec ... \+} or @samp{-execdir ... \+} are invoked
-before the program is exited.
+running.  Any command lines which have been built by @samp{-exec
+... \+} or @samp{-execdir ... \+} are invoked before the program is
+exited.  After @samp{-quit} is executed, no more files specified on
+the command line will be processed.  For example, @samp{find /tmp/foo
+/tmp/bar -print -quit} will print only @samp{/tmp/foo}.  One common
+use of @samp{-quit} is to stop searching the file system once we have
+found what we want.  For example, if we want to find just a single
+file we can do this:
+@example
+find / -name needle -print -quit
+@end example
+@noindent
 @end deffn
 
 @deffn Option -noleaf

find/find.1

@@ -1174,7 +1174,11 @@ returns a non-zero exit status.  If
 .B find
 encounters an error, this can sometimes cause an
 immediate exit, so some pending commands may not be run
-at all.  This variant of
+at all.  For this reason
+.B \-exec my-command ... {} \e+ \-quit
+may not result in
+.B my-command
+actually being run.  This variant of
 .B \-exec
 always returns true.
 
@@ -1623,18 +1627,38 @@ find . \-path ./src/emacs \-prune \-o \-print
 
 
 .IP "\-quit"
-Exit immediately.  No child processes will be left running, but no more
-paths specified on the command line will be processed.  For example,
-.B find /tmp/foo /tmp/bar \-print \-quit
-will print only
-.BR /tmp/foo .
-Any command lines which have been built up with
-.B \-execdir \&...\& {} +
-will be invoked before
+Exit immediately (with return value zero if no errors have occurred).
+This is different to
+.B \-prune
+because
+.B \-prune
+only applies to the contents of pruned directories, while
+.B \-quit
+simply makes
 .B find
-exits.
-The exit status may or may not be zero,
-depending on whether an error has already occurred.
+stop immediately.  No child processes will be left
+running.  Any command lines which have been built by
+.B \-exec ... \e+
+or
+.B \-execdir ... \e+
+are invoked before the program is
+exited.  After
+.B \-quit
+is executed, no more files specified onthe command line will be
+processed.  For example,
+.RB ` find
+.B /tmp/foo /tmp/bar -print
+.BR -quit `
+will print only `/tmp/foo`.  One common use of
+.B \-quit
+is to stop searching the file system once we have
+found what we want.  For example, if we want to find just a single
+file we can do this:
+.br
+.in +1i
+find / -name needle -print -quit
+.br
+.in -1i
 
 .SS OPERATORS
 .P
@@ -2234,6 +2258,13 @@ which is otherwise equivalent to the longer, yet more portable:
 .B find /tmp \e( \-type f \-o \-type d \-o \-type l \e)
 .fi
 
+Search for files with a particular name and stop immediately when we
+find the first one:
+
+.nf
+.B find / -name needle -print -quit
+.fi
+
 .SH EXIT STATUS
 .PP
 .B find