Date: 17 Jan 2003 13:21:14 -0800 From: "Gary W. Swearingen" <swear@attbi.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/47170: xargs(1) manpage has "utility" problems. Message-ID: <hzadhzscad.dhz@localhost.localdomain>
next in thread | raw e-mail | index | archive | help
>Number: 47170 >Category: docs >Synopsis: xargs(1) manpage has "utility" problems. >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Fri Jan 17 13:30:01 PST 2003 >Closed-Date: >Last-Modified: >Originator: Gary W. Swearingen >Release: FreeBSD 4.7-STABLE i386 >Organization: none >Environment: n/a ================ >Description: The manpage refers to both xargs(1) and one of its arguments as "utility", often in a manner that is confusing or awkward, especially in formats (eg, in Emacs) where the word is looks the same as an argument or a normal word. Sometimes the manpage uses "the utility" and sometimes it omits the "the". The worst problem is "The utility and any arguments specified on the command line are given to the utility". While this eventually makes sense, it can take some head scratching. The argv[0] usage should go without mention; it's standard behavior and mentioning it just confuses things. Also: The manpage uses both "xargs utility" and "xargs command". ================ >How-To-Repeat: n/a ================ >Fix: Replace "xargs utility" with "xargs command" and clean up other uses of "utility", "the utility", etc. Patch this: .\" $FreeBSD: src/usr.bin/xargs/xargs.1,v 1.6.2.9 2002/06/23 08:01:27 jmallett Exp $ with this: --- /pr/work/xargs..orig.1 Tue Jan 14 17:35:06 2003 +++ /pr/work/xargs.1 Tue Jan 14 19:14:42 2003 @@ -62,19 +62,18 @@ .Sh DESCRIPTION The .Nm -utility reads space, tab, newline and end-of-file delimited arguments -from the standard input and executes the specified +command reads space, tab, newline and end-of-file delimited strings +from the standard input and executes .Ar utility -with them as +with the strings as arguments. .Pp -The utility and any arguments specified on the command line are given -to the +Any arguments specified on the command line are given to .Ar utility upon each invocation, followed by some number of the arguments read -from standard input. -The -.Ar utility +from the standard input of +.Nm . +The utility is repeatedly executed until standard input is exhausted. .Pp Spaces, tabs and newlines may be embedded in arguments using single @@ -175,7 +174,8 @@ will be called with the available lines. .It Fl n Ar number Set the maximum number of arguments taken from standard input for each -invocation of the utility. +invocation of +.Ar utility . An invocation of .Ar utility will use less than @@ -229,9 +229,9 @@ arguments will not fit in the specified (or default) command line length. .El .Pp -If no +If .Ar utility -is specified, +is omitted, .Xr echo 1 is used. .Pp @@ -241,15 +241,19 @@ .Pp The .Nm -utility exits immediately (without processing any further input) if a +command exits immediately (without processing any further input) if a command line cannot be assembled, .Ar utility -cannot be invoked, an invocation of the utility is terminated by a signal -or an invocation of the utility exits with a value of 255. +cannot be invoked, an invocation of +.Ar utility +is terminated by a signal, +or an invocation of +.Ar utility +exits with a value of 255. .Sh DIAGNOSTICS The .Nm -utility exits with a value of 0 if no error occurs. +command exits with a value of 0 if no error occurs. If .Ar utility cannot be found, @@ -269,7 +273,7 @@ .Sh STANDARDS The .Nm -utility is expected to be +command is expected to be .St -p1003.2 compliant. The >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?hzadhzscad.dhz>