From owner-freebsd-doc Mon Jan 27 13:23:58 2003 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 3C98837B401; Mon, 27 Jan 2003 13:23:57 -0800 (PST) Received: from rwcrmhc53.attbi.com (rwcrmhc53.attbi.com [204.127.198.39]) by mx1.FreeBSD.org (Postfix) with ESMTP id 78FA343ED8; Mon, 27 Jan 2003 13:23:55 -0800 (PST) (envelope-from swear@attbi.com) Received: from localhost.localdomain ([12.242.158.67]) by rwcrmhc53.attbi.com (rwcrmhc53) with ESMTP id <20030127212349053001sluie>; Mon, 27 Jan 2003 21:23:49 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h0RLLTm9043795; Mon, 27 Jan 2003 13:21:34 -0800 (PST) (envelope-from swear@attbi.com) Received: (from jojo@localhost) by localhost.localdomain (8.12.6/8.12.5/Submit) id h0RLLO3j043792; Mon, 27 Jan 2003 13:21:24 -0800 (PST) (envelope-from swear@attbi.com) X-Authentication-Warning: localhost.localdomain: jojo set sender to swear@attbi.com using -f To: Tom Rhodes Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/47170: xargs(1) manpage has "utility" problems. References: <200301271818.h0RIIXd2052968@freefall.freebsd.org> From: swear@attbi.com (Gary W. Swearingen) Date: 27 Jan 2003 13:21:23 -0800 In-Reply-To: <200301271818.h0RIIXd2052968@freefall.freebsd.org> Message-ID: Lines: 36 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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 Tom Rhodes writes: > 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. You mean like the crontab(1) manpage which uses that once, and then uses "this command" 7 times and "The crontab(1) command" once, and which says "FreeBSD General Commands Manual" at the top of the displayed page? ^^^^^^^^ This will find many other examples: find $(manpath|sed s/:/\ /g) | xargs zgrep command /dev/null Even sh(1) says "The shell is a command that [...] executes other commands" after starting out "This utility" and never using it again. Here's a few manpages which begin "The [] command": pkg_which(1), pkgdepfix(1), tk(n), message(n). Now, I don't have a big problem with "utility" if you do a good job un-confusing it with the "utility" argument, but it seems like a tough job. Some manpages use "The ... program"; you might use that to avoid confusion with the "utility" argument (or vice versa?) if you don't like "command". ("Program" is actually better as it doesn't needlessly seem to be classifying programs as utilities, tools, applications, etc. Finally, note that several manpages document a program linked with several filenames. It can be useful to refer to both the program and to the commands which cause the program to run and which are being documented by the manpage. Ideally, programs would not be mentioned in most manpages; they are implementation details. It is commands which should be documented (at least in sections 1 and 8). To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message