Date: Mon, 27 Jan 2003 17:19:26 -0500 From: Tom Rhodes <trhodes@FreeBSD.org> 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: <fuu1fujnl8.1fu@localhost.localdomain> References: <200301271818.h0RIIXd2052968@freefall.freebsd.org> <fuu1fujnl8.1fu@localhost.localdomain>
next in thread | previous in thread | raw e-mail | index | archive | help
On 27 Jan 2003 13:21:23 -0800
swear@attbi.com (Gary W. Swearingen) wrote:
> Tom Rhodes <trhodes@FreeBSD.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030127171926.6b7963b5.trhodes>