Shorten text pointing from -X to -print0.

Add pointer from -print0 to xargs(1).
Add an EXAMPLE to demonstrate \( ... -or ... \) -print0.
Stop advertising -print | xargs, which is dangerous.
Add a CAVEAT about passing find(1) output to other programs.

Mostly from joachimschipper dot nl;
using feedback from jmc@ and sthen@, and tweaked myself;
ok jmc@

1 files changed, 32 insertions, 12 deletions

diff --git a/usr.bin/find/find.1 b/usr.bin/find/find.1
index ae5d7774660..9f8b6693a85 100644
--- a/usr.bin/find/find.1
+++ b/usr.bin/find/find.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: find.1,v 1.78 2010/07/15 20:51:38 schwarze Exp $
+.\"	$OpenBSD: find.1,v 1.79 2010/09/19 23:48:58 schwarze Exp $
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -31,7 +31,7 @@
 .\"
 .\"	from: @(#)find.1	8.1 (Berkeley) 6/6/93
 .\"
-.Dd $Mdocdate: July 15 2010 $
+.Dd $Mdocdate: September 19 2010 $
 .Dt FIND 1
 .Os
 .Sh NAME
@@ -126,13 +126,9 @@ quotes, backslash
 space, tab, and newline
 .Pq Sq \en
 characters.
-Alternatively, the
+Consider using
 .Fl print0
-primary may be used in conjunction with the
-.Fl 0
-option to
-.Xr xargs 1 ,
-allowing all file names to be processed safely.
+instead.
 .It Fl x
 Prevents
 .Nm
@@ -386,7 +382,10 @@ character.
 .It Ic -print0
 This primary always evaluates to true.
 It prints the pathname of the current file to standard output, followed
-by a null character.
+by a null character, suitable for use with the
+.Fl 0
+option to
+.Xr xargs 1 .
 .It Ic -prune
 This primary always evaluates to true.
 It causes
@@ -525,11 +524,12 @@ ending in a dot and single digit, but skip directory
 .Pp
 .Dl "$ find /usr/src -path /usr/src/gnu -prune -or -name \e*.[0-9]"
 .Pp
-Find and remove all *.jpg files in the current working directory:
+Find and remove all *.jpg and *.gif files under the current working
+directory:
 .Pp
-.Dl "$ find . -name \e*.jpg -exec rm {} \e;"
+.Dl "$ find . \e( -name \e*.jpg -or -name \e*.gif \e) -exec rm {} \e;
 or
-.Dl "$ find . -name \e*.jpg | xargs rm"
+.Dl "$ find . \e( -name \e*.jpg -or -name \e*.gif \e) -print0 | xargs -0r rm"
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chmod 1 ,
@@ -638,6 +638,26 @@ and
 .Ql \&;
 may have to be escaped from the shell.
 .Pp
+Passing the output of
+.Nm
+to other programs requires some care:
+.Pp
+.Dl "$ find . -name \e*.jpg | xargs rm"
+or
+.Dl "$ rm `find . -name \e*.jpg`"
+.Pp
+would, given files
+.Dq important\ .jpg
+and
+.Dq important ,
+remove
+.Dq important .
+Use the
+.Ic -print0
+or
+.Ic -exec
+primaries instead.
+.Pp
 As there is no delimiter separating options and file names or file
 names and the
 .Ar expression ,