From owner-cvs-all Fri Nov 12 3:16:19 1999 Delivered-To: cvs-all@freebsd.org Received: from mppsystems.com (dslmpp.pro-ns.net [208.210.148.205]) by hub.freebsd.org (Postfix) with ESMTP id 90A6914C9E; Fri, 12 Nov 1999 03:16:09 -0800 (PST) (envelope-from mpp@mppsystems.com) Received: (from mpp@localhost) by mppsystems.com (8.9.3/8.9.3) id FAA62103; Fri, 12 Nov 1999 05:15:28 -0600 (CST) (envelope-from mpp) Date: Fri, 12 Nov 1999 05:15:28 -0600 From: Mike Pritchard To: Sheldon Hearn Cc: Nik Clayton , Greg Lehey , Bruce Evans , 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> References: <19991111235932.A62263@catkin.nothing-going-on.org> <6216.942392728@axl.noc.iafrica.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <6216.942392728@axl.noc.iafrica.com> Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk 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