* doc/find.texti (Option -files0-from file) use @example for the
example and cartouche to highlight the itemised list of caveats.
---
doc/find.texi | 50 ++++++++++++++++++++++++++++++++++----------------
1 file changed, 34 insertions(+), 16 deletions(-)
diff --git a/doc/find.texi b/doc/find.texi
index 59d29bf9..30d629dc 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -429,26 +429,44 @@ The processing of the starting points is otherwise as
usual, e.g. @code{find}
will recurse into subdirectories unless otherwise prevented.
To process only the starting points, one can additionally pass @samp{-maxdepth
0}.
-Further notes:
-if a file is listed more than once in the input file, it is unspecified
-whether it is visited more than once.
-If the @file{file} is mutated during the operation of @code{find}, the result
-is unspecified as well.
-Finally, the seek position within the named @samp{file} at the time @code{find}
-exits, be it with @samp{-quit} or in any other way, is also unspecified.
-By "unspecified" here is meant that it may or may not work or do any specific
-thing, and that the behavior may change from platform to platform, or from
-findutils release to release.
-
-Example:
-Given that another program @code{proggy} pre-filters and creates a huge
-NUL-separated list of files, process those as starting points, and find
-all regular, empty files among them:
+@cartouche Warnings
+In order to use this option safely, you need to take care about some
+specific things:
+
+@itemize @bullet
+@item Ensure there are no duplicate entries
+ @itemize @minus{}
+ @item Otherwise, some files may (or may not) be visited more than once.
+ @end itemize
+@item Do not modify the file while @code{find} is running
+ @itemize @minus{}
+ @item The effects of any concurrent modification are unspecified.
+ @end itemize
+@item Do not rely on the final seek position in the file
+ @itemize @minus{}
+ @item There is no guarantee about the final seek position. It may
+ vary between platforms, between findutils release, or even between
+ runs of @file{find}.
+ @item Therefore, sharing the same open file between
+ @samp{-files0-from} and anything else (including use of
+ @samp{-files0-from} in another instance of the @code{find}
+ program) is unlikely to reliably do what you want.
+ Instead if you need to read from the same file in more
+ than one program, open it separately for each.
+ @end itemize
+@end itemize
+@end cartouche
+
+Suppose that some program @code{proggy} pre-filters and creates a huge
+NUL-separated list of files, we can process those as starting points,
+and find all regular, empty files among them:
+
@example
$ proggy | find -files0-from - -maxdepth 0 -type f -empty
@end example
+
The use of @samp{-files0-from -} means to read the names of the starting points
-from standard input, i.e., from the pipe; and @samp{-maxdepth 0} ensures that
+from standard input, i.e., from the pipe. Using @samp{-maxdepth 0} ensures
that
only explicitly those entries are examined without recursing into directories
(in the case one of the starting points is one).
@end deffn
--
2.39.5
