From owner-freebsd-doc Mon Jan 27 14:19:16 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 DB2A837B401 for ; Mon, 27 Jan 2003 14:19:14 -0800 (PST) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9E6F243F5B for ; Mon, 27 Jan 2003 14:19:13 -0800 (PST) (envelope-from trhodes@FreeBSD.org) Received: from moble.pittgoth.com ([192.168.0.5]) by pittgoth.com (8.12.6/8.12.6) with SMTP id h0RMJ6Od052068; Mon, 27 Jan 2003 17:19:06 -0500 (EST) (envelope-from trhodes@FreeBSD.org) Date: Mon, 27 Jan 2003 17:19:26 -0500 From: Tom Rhodes To: swear@attbi.com (Gary W. Swearingen) Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/47170: xargs(1) manpage has "utility" problems. Message-Id: <20030127171926.6b7963b5.trhodes@FreeBSD.org> In-Reply-To: References: <200301271818.h0RIIXd2052968@freefall.freebsd.org> X-Mailer: Sylpheed version 0.8.6claws (GTK+ 1.2.10; i386-portbld-freebsd5.0CUR) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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 On 27 Jan 2003 13:21:23 -0800 swear@attbi.com (Gary W. Swearingen) wrote: > 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. Actually I like `command' the only thing here was that I didn't really want to remove the .Nm utility which was already there. On another note, I would extremely like to unconfuse the entire utility mess within this manual page! I see how a user can get confused quickly. > > 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). > I like the idea of documenting drivers and kernel functions also though. On an off the wall note, a recent commit removed the NW from disklabel. This may help your patch ;) Thanks for all the comments and help, Gary. -- Tom Rhodes To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message