Date: Fri, 12 Nov 1999 05:15:28 -0600 From: Mike Pritchard <mpp@mppsystems.com> To: Sheldon Hearn <sheldonh@uunet.co.za> Cc: Nik Clayton <nik@FreeBSD.org>, Greg Lehey <grog@lemis.com>, Bruce Evans <bde@zeta.org.au>, obrien@NUXI.com, cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/contrib/grep/doc grep.1 Message-ID: <19991112051528.A62006@mppsystems.com> In-Reply-To: <6216.942392728@axl.noc.iafrica.com> References: <19991111235932.A62263@catkin.nothing-going-on.org> <6216.942392728@axl.noc.iafrica.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Nov 12, 1999 at 09:45:28AM +0200, Sheldon Hearn wrote: > > > On Thu, 11 Nov 1999 23:59:32 GMT, Nik Clayton wrote: > > > I concur with Greg. "The cat(1) command..." or "The cat(1) utility" > > (or even "The /etc/rc.conf file...") all read as being stilted and > > redundant. > > By the way, I thought about the argument that the use of mixed case > forces the reader to verify the case of the actual command. Since we > always use the correct case in the synopsis, I'm not even sure that > there's anything wrong with using mixed case in the manpages. > > :-) > > And this from someone who has diffs to convert man1/[a-c]*.1 . :-) As someone else who has fixed many a man page, if I see a case like: Cat will do... I will change it to: The cat command/utility/whatever will do... If also happen to be fixing something else in the man page. I don't go out of my way to change the first case anymore, probably more due to a lack of time than anything. Things like func() does.... I'll usually leave alone as long as the case matches the actual command/function. But if I can find a less "stilted" way to re-word the whole line, I will do so. The reasons for this are that I want the automated man page checking tools/scripts to not complain about invalid references due to caplitization differences. It makes for a real headache trying to find real problems in the man pages when the scripts complain about a zillion problems due to case differences. I cleaned a bunch of them up a long time ago, but they always creep back in. And before someone says "who cares?", there are a number of places where that leading capitial letter makes all the difference in the world. I saw one of the followups to this message from someone that states that the Open Writers Group (?) states that things like this should be worded as: The _name_ command/function/utility/gizmo blah blah blah... instead of: _Name_ command/func/utility/gizmo blah blah blah. Which I prefer, even though people think it sounds stilted. At least it removes some of the ambiguity as to exactly what is being documented. -Mike -- Mike Pritchard mpp@FreeBSD.org or mpp@mppsystems.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19991112051528.A62006>