Date: 27 Jan 2003 13:21:23 -0800 From: swear@attbi.com (Gary W. Swearingen) To: Tom Rhodes <trhodes@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/47170: xargs(1) manpage has "utility" problems. Message-ID: <fuu1fujnl8.1fu@localhost.localdomain> In-Reply-To: <200301271818.h0RIIXd2052968@freefall.freebsd.org> References: <200301271818.h0RIIXd2052968@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?fuu1fujnl8.1fu>