Hi,
I like these two and have tweaked them a bit.
Joachim Schipper wrote on Mon, Sep 13, 2010 at 02:49:58PM +0200:
> The first diff changes the last example in find(1). This diff:
> - makes it clear that it, in fact, works on all files *under* (not just
> "in") the current working directory;
> - adds handling of *.gif files to illustrate ordering;
> - changes to -print0 | xargs -0r to illustrate proper form.
>
> The second diff is relative to the first diff, and adds the following
> warning to CAVEATS:
[...]
My tweaks:
* regarding -print:
"should not" is not nice in manuals, let's say "is dangerous".
* regarding -print0:
Point to xargs(1) -0, it nicely fits on the same line.
* EXAMPLES:
"remove all *.jpg and *.gif files" (not "or")
Also, give the pointer to CAVEATS in a more concise form.
* CAVEATS:
Using the newline might mislead people to underestimate the danger:
Who ever uses newlines in filenames?
Better use the space character for demonstration purposes.
And don't recommend -X, it is rarely doing the job, if at all.
> This is already addressed in the man page (e.g. under the description of
> -print0 or -X), but many people (including the EXAMPLES) get it wrong;
> hopefully the above warning (and the references from the description of
> -print and the EXAMPLES section) prevents some people from making this
> mistake.
Even if this introduces some more redundancy, self-contained descriptions
for all options (-X, -print, and -print0) are good, and EXAMPLES and
CAVEATS are good places to help inexperienced users, even using some
verbosity if need be, so i don't think this is overdone.
OK to commit?
Index: find.1
===================================================================
RCS file: /cvs/src/usr.bin/find/find.1,v
retrieving revision 1.78
diff -u -r1.78 find.1
--- find.1 15 Jul 2010 20:51:38 -0000 1.78
+++ find.1 13 Sep 2010 23:35:00 -0000
@@ -383,10 +383,17 @@
by a newline
.Pq Ql \en
character.
+This is dangerous in conjunction with
+.Xr xargs 1 ,
+see
+.Sx CAVEATS .
.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 +532,13 @@
.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
+.Pq see also Sx CAVEATS :
.Pp
-.Dl "$ find . -name \e*.jpg -exec rm {} \e;"
+.Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -exec rm {} \e;
or
-.Dl "$ find . -name \e*.jpg | xargs rm"
+.Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -print0 | xargs -0r rm"
.Sh SEE ALSO
.Xr chflags 1 ,
.Xr chmod 1 ,
@@ -637,6 +646,24 @@
and
.Ql \&;
may have to be escaped from the shell.
+.Pp
+Using
+.Nm
+in combination with
+.Xr xargs 1
+requires some care:
+.Pp
+.Dl "$ find . -name \e*.jpg | xargs rm"
+.Pp
+would, given a file named
+.Pa "important .jpg"
+(with a space character in the middle), remove
+.Pa 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
