From owner-freebsd-doc Mon Aug 9 15:40: 5 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 10DEC150A7 for ; Mon, 9 Aug 1999 15:40:01 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id XAA78188; Mon, 9 Aug 1999 23:27:41 +0100 (BST) (envelope-from nik) Date: Mon, 9 Aug 1999 23:27:41 +0100 From: Nik Clayton To: Tim Vanderhoek Cc: freebsd-doc@freebsd.org Subject: Re: docs/13020: Manpage capitalization Message-ID: <19990809232741.A77237@catkin.nothing-going-on.org> References: <199908081400.HAA63051@freefall.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <199908081400.HAA63051@freefall.freebsd.org>; from Tim Vanderhoek on Sun, Aug 08, 1999 at 07:00:03AM -0700 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org My opinion, for what it's worth: On Sun, Aug 08, 1999 at 07:00:03AM -0700, Tim Vanderhoek wrote: > The _New_Hacker_Dictionary_ suggests moving function-names, etc. away > from the beginning of sentences. I usually try to do this. In lue of > that, I prefer writing "The gack() will return NULL on failure.". I > appear to be alone in preferring this to "The gack() function will > return NULL on failure.". I try and avoid these where ever possible, trying to remove redundant phrases from the documentation. For example; Edit the /etc/fstab file when you add a new disk. vs. Edit /etc/fstab when you add a new disk. (The second approach, is, IMHO, better). I have no problem with lower case function names at the beginning of sentances. To use an analogy, if you were writing about the company "eTrade", you wouldn't capitalise the first "e" if the company name was the first word in a sentance. And as regards things like Perl/perl(1), use "Perl" (or "Sendmail", or "Apache") when you're talking about the application, and use "perl(1)" (or "sendmail(1)", or "httpd(1)") when you're talking about the specific command that the reader is expected to type. N -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message