Date: Mon, 9 Aug 1999 23:27:41 +0100 From: Nik Clayton <nik@freebsd.org> To: Tim Vanderhoek <vanderh@ecf.utoronto.ca> Cc: freebsd-doc@freebsd.org Subject: Re: docs/13020: Manpage capitalization Message-ID: <19990809232741.A77237@catkin.nothing-going-on.org> In-Reply-To: <199908081400.HAA63051@freefall.freebsd.org>; from Tim Vanderhoek on Sun, Aug 08, 1999 at 07:00:03AM -0700 References: <199908081400.HAA63051@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990809232741.A77237>