[PATCH] find: doc: Fix -prune SCM example/directories and make it more efficient

[raf]

* find/find.1 - Fix -prune SCM example directories and make it more efficient
* doc/find.texi - Fix -prune SCM example and make it more efficient (two ways)
* NEWS - Describe the above
---
 NEWS          |  3 +++
 doc/find.texi | 27 ++++++++++++++++++++++-----
 find/find.1   | 15 +++++++++++++--
 3 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/NEWS b/NEWS
index 1fff34f8..fa73d675 100644
--- a/NEWS
+++ b/NEWS
@@ -18,6 +18,9 @@ GNU findutils NEWS - User visible changes.      -*- outline 
-*- (allout)
   When generating the Texinfo manual, `makeinfo` is invoked with the --no-split
   option for all output formats now; this avoids files like find.info-[12].
 
+  The find.texi -prune SCM example has been fixed, the find.1 -prune SCM 
example
+  directories/output have been fixed, and the example itself has been made more
+  efficient (both files). [#62259] Also, a typo in find.texi has been fixed.
 
 * Noteworthy changes in release 4.9.0 (2022-02-22) [stable]
 
diff --git a/doc/find.texi b/doc/find.texi
index 379fe646..fec89d3a 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -5137,14 +5137,16 @@ searching subdirectories inside projects whose SCM 
directory we
 already found.
 
 @smallexample
-find repo/ \
--exec test -d @{@}/.svn \; -or \
--exec test -d @{@}/.git \; -or \
--exec test -d @{@}/CVS \; -print -prune
+find -L repo/ \
+-type d \
+\( -exec test -d @{@}/.svn \; \
+-or -exec test -d @{@}/.git \; \
+-or -exec test -d @{@}/CVS \; \
+\) -print -prune
 @end smallexample
 
 In this example, @command{test} is used to tell if we are currently
-examining a directory which appears to the a project's root directory
+examining a directory which appears to be a project's root directory
 (because it has an SCM subdirectory).  When we find a project root,
 there is no need to search inside it, and @code{-prune} makes sure
 that we descend no further.
@@ -5153,6 +5155,21 @@ For large, complex trees like the Linux kernel, this 
will prevent
 searching a large portion of the structure, saving a good deal of
 time.
 
+The @samp{-type d} clause causes the three @samp{test} shell
+processes to only be executed for directories. This can be made even
+more efficient by combining the three @samp{test} shell processes
+into a single process:
+
+@smallexample
+find -L repo/ \
+-type d \
+-exec sh -c 'test -d "$1"/.svn || test -d "$1"/.git || test -d "$1"/CVS' . {} 
\; \
+-print -prune
+@end smallexample
+
+Note that the @samp{.} argument is just a placeholder for the unused
+@samp{$0} shell positional parameter in the @samp{sh -c} command. The
+@samp{@{@}} argument is the @samp{$1} shell positional parameter.
 
 @node Security Considerations
 @chapter Security Considerations
diff --git a/find/find.1 b/find/find.1
index 429aa2f0..aa330c95 100644
--- a/find/find.1
+++ b/find/find.1
@@ -2492,8 +2492,9 @@ projects' roots:
 .nf
 \&
 .in +4m
-.B $ find repo/ \e
+.B $ find -L repo/ \e
 .in +4m
+.B \-type d \e
 .B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e
 .B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e
 .B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e
@@ -2502,7 +2503,7 @@ projects' roots:
 .in -4m
 \&
 .fi
-Sample output:
+Sample directories:
 .nf
 \&
 .in +4m
@@ -2513,6 +2514,16 @@ Sample output:
 .B repo/project4/.git
 .in
 \&
+Sample output:
+.nf
+\&
+.in +4m
+.B repo/project1
+.B repo/gnu/project2
+.B repo/gnu/project3
+.B repo/project4
+.in
+\&
 .fi
 In this example,
 .B \-prune
-- 
2.30.2