From swear@attbi.com  Fri Jan 17 13:22:31 2003
Return-Path: <swear@attbi.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 5305537B401
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 17 Jan 2003 13:22:31 -0800 (PST)
Received: from rwcrmhc51.attbi.com (rwcrmhc51.attbi.com [204.127.198.38])
	by mx1.FreeBSD.org (Postfix) with ESMTP id C448B43F18
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 17 Jan 2003 13:22:30 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: from localhost.localdomain (<unknown.domain>[12.242.158.67])
          by rwcrmhc51.attbi.com (rwcrmhc51) with ESMTP
          id <2003011721223005100po0hqe>; Fri, 17 Jan 2003 21:22:30 +0000
Received: from localhost.localdomain (localhost [127.0.0.1])
	by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h0HLLKm9045642
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 17 Jan 2003 13:21:20 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: (from jojo@localhost)
	by localhost.localdomain (8.12.6/8.12.5/Submit) id h0HLLEoV045639;
	Fri, 17 Jan 2003 13:21:14 -0800 (PST)
	(envelope-from swear@attbi.com)
Message-Id: <hzadhzscad.dhz@localhost.localdomain>
Date: 17 Jan 2003 13:21:14 -0800
From: "Gary W. Swearingen" <swear@attbi.com>
Reply-To: swear@attbi.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: xargs(1) manpage has "utility" problems.
X-GNATS-Notify:

>Number:         47170
>Category:       docs
>Synopsis:       xargs(1) manpage has "utility" problems.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jan 17 13:30:01 PST 2003
>Closed-Date:    Wed Feb 05 11:24:59 PST 2003
>Last-Modified:  Wed Feb 05 11:24:59 PST 2003
>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:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Mon Jan 27 10:16:52 PST 2003 
State-Changed-Why:  
Slightly different version committed.  Using command in place of utility is 
a little out of tune with how other manual pages read (or should read) 
where: 
The 
.Nm 
utility 
is used.  I agree that .Ar utility and .Nm utility is confusing here 
and I'll work on sorting this out.  Thanks for the submission Gary! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Mon Jan 27 10:16:52 PST 2003 
Responsible-Changed-Why:  
Slightly different version committed.  Using command in place of utility is 
a little out of tune with how other manual pages read (or should read) 
where: 
The 
.Nm 
utility 
is used.  I agree that .Ar utility and .Nm utility is confusing here 
and I'll work on sorting this out.  Thanks for the submission Gary! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47170 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 5 11:24:27 PST 2003 
State-Changed-Why:  
I've synced my changes.  Thanks for the submission Gary. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47170 
>Unformatted:
