From owner-freebsd-doc Fri Jan 17 13:30: 8 2003 Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 56B8B37B401 for ; Fri, 17 Jan 2003 13:30:04 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 5BE8443F13 for ; Fri, 17 Jan 2003 13:30:02 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.6/8.12.6) with ESMTP id h0HLU2NS084789 for ; Fri, 17 Jan 2003 13:30:02 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.6/8.12.6/Submit) id h0HLU2vU084788; Fri, 17 Jan 2003 13:30:02 -0800 (PST) Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5305537B401 for ; 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 ; Fri, 17 Jan 2003 13:22:30 -0800 (PST) (envelope-from swear@attbi.com) Received: from localhost.localdomain ([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 ; 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: Date: 17 Jan 2003 13:21:14 -0800 From: "Gary W. Swearingen" Reply-To: swear@attbi.com To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/47170: xargs(1) manpage has "utility" problems. Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org >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