doc: improve description of 'find -delete'

* doc/find.texi (Action -delete): Improve and re-structure:
Mention that -delete is able to remove directories (if they are empty),
that failure to delete a file changes the exit code to nonzero, and
clarify better the relation between -delete, -depth and -prune.
* find/find.1 (-delete): Align with the above mentioned section in the
Texinfo manual.

Fixes https://savannah.gnu.org/bugs/?61774
Originally reported by Chris Davies in
  https://bugs.debian.org/1003339

Co-authored-by: Bernhard Voelker <mail@bernhard-voelker.de>

3 files changed, 61 insertions, 37 deletions

diff --git a/NEWS b/NEWS
index 0e046cf4..9ed521a0 100644
--- a/NEWS
+++ b/NEWS
@@ -32,6 +32,9 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
   Furthermore, both add the description of the -printf format directive '%B',
   for a file's birth time, and its limitations. [#61327]
 
+  The description of the -delete action has been improved and aligned among
+  the manual page and the Texinfo documentation.
+
   The output of 'find --help' now reads better.
 
   The HTML online manual is using the official GNU stylesheet again.
diff --git a/doc/find.texi b/doc/find.texi
index cb738d12..0cc25504 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -2970,21 +2970,35 @@ with @samp{y} or @samp{Y}.  Implies @samp{-t}.
 
 @deffn Action -delete
 Delete files or directories; true if removal succeeded.  If the
-removal failed, an error message is issued.
+removal failed, an error message is issued and @code{find}'s exit status
+will be nonzero (when it eventually exits).
+
+@quotation Warning
+Don't forget that @code{find} evaluates the command line as an expression,
+so putting @samp{-delete} first will make @code{find} try to delete everything
+below the starting points you specified.
+@end quotation
 
 The use of the @samp{-delete} action on the command line automatically
-turns on the @samp{-depth} option (@pxref{find Expressions}).  This
-can be surprising if you were previously just testing with
-@samp{-print}, so it is usually best to remember to use @samp{-depth}
-explicitly.
+turns on the @samp{-depth} option.
+As in turn @samp{-depth} makes @samp{-prune} ineffective, the @samp{-delete}
+action cannot usefully be combined with @samp{-prune}.
+
+Often, the user might want to test a @code{find} command line with @samp{-print}
+prior to adding @samp{-delete} for the actual removal run.  To avoid surprising
+results, it is usually best to remember to use @samp{-depth} explicitly during
+those earlier test runs.
+
+See @ref{Cleaning Up} for a deeper discussion about good use cases of the
+@samp{-delete} action and those with surprising results.
 
-If @samp{-delete} fails, @code{find}'s exit status will be nonzero
-(when it eventually exits).
+The @samp{-delete} action will fail to remove a directory unless it is empty.
 
 Together with the @samp{-ignore_readdir_race} option, @code{find} will
 ignore errors of the @samp{-delete} action in the case the file has disappeared
-since the parent directory was read: it will not output an error diagnostic, and
-the return code of the @samp{-delete} action will be true.
+since the parent directory was read: it will not output an error diagnostic, not
+change the exit code to nonzero, and the return code of the @samp{-delete}
+action will be true.
 @end deffn
 
 @node Adding Tests
diff --git a/find/find.1 b/find/find.1
index bda89575..6bad0096 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1167,42 +1167,47 @@ does not check.
 
 .SS ACTIONS
 .IP "\-delete\fR"
-Delete files; true if removal succeeded.  If the removal failed, an
-error message is issued.
-If
-.B \-delete
-fails,
+Delete files or directories; true if removal succeeded.
+If the removal failed, an error message is issued and
 .BR find 's
-exit status will be nonzero
-(when it eventually exits).
-Use of
-.B \-delete
-automatically turns on the
-.RB ` \-depth '
-option.
+exit status will be nonzero (when it eventually exits).
 
-.BR Warnings :
-Don't forget that the find command line is
-evaluated as an expression, so putting
+.BR Warning :
+Don't forget that
+.B find
+evaluates the command line as an
+expression, so putting
 .B \-delete
 first will make
 .B find
 try to delete everything below the starting points you specified.
-When testing a
-.B find
-command line that you later intend to use with
-.BR \-delete ,
-you should explicitly specify
-.B \-depth
-in order to avoid later surprises.  Because
+
+The use of the
 .B \-delete
-implies
-.BR \-depth ,
-you cannot usefully use
+action on the command line automatically turns on the
+.B \-depth
+option.
+As in turn
+.B \-depth
+makes
 .B \-prune
-and
+ineffective, the
 .B \-delete
-together.
+action cannot usefully be combined with
+.BR \-prune .
+
+Often, the user might want to test a find command line with
+.B \-print
+prior to adding
+.B \-delete
+for the actual removal run.
+To avoid surprising results, it is usually best to remember to use
+.B \-depth
+explicitly during those earlier test runs.
+
+The
+.B \-delete
+action will fail to remove a directory unless it is empty.
 
 Together with the
 .B \-ignore_readdir_race
@@ -1211,10 +1216,12 @@ option,
 will ignore errors of the
 .B \-delete
 action in the case the file has disappeared since the parent directory was
-read: it will not output an error diagnostic, and the return code of the
+read: it will not output an error diagnostic, not change the exit code to
+nonzero, and the return code of the
 .B \-delete
 action will be true.
 
+
 .IP "\-exec \fIcommand\fR ;"
 Execute
 .IR command ;