From owner-freebsd-doc Tue Dec 7 9:36:34 1999 Delivered-To: freebsd-doc@freebsd.org Received: from mppsystems.com (dslmpp.pro-ns.net [208.210.148.205]) by hub.freebsd.org (Postfix) with ESMTP id 092FA14D06 for ; Tue, 7 Dec 1999 09:36:24 -0800 (PST) (envelope-from mpp@mppsystems.com) Received: (from mpp@localhost) by mppsystems.com (8.9.3/8.9.3) id FAA05877; Tue, 7 Dec 1999 05:38:19 -0600 (CST) (envelope-from mpp) Date: Tue, 7 Dec 1999 05:38:19 -0600 From: Mike Pritchard To: Chris Costello Cc: freebsd-doc@freebsd.org Subject: Re: docs/15234: sh(1) man page have capitalised instance of "sh". Message-ID: <19991207053818.B5628@mppsystems.com> References: <199912070330.TAA19258@freefall.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre3i In-Reply-To: <199912070330.TAA19258@freefall.freebsd.org> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Mon, Dec 06, 1999 at 07:30:02PM -0800, Chris Costello wrote: > The following reply was made to PR docs/15234; it has been noted by GNATS. > > From: Chris Costello > To: "Oleg V. Volkov" > Cc: freebsd-gnats-submit@freebsd.org > Subject: Re: docs/15234: sh(1) man page have capitalised instance of "sh". > Date: Mon, 06 Dec 1999 21:25:18 -0600 > > On Tue, Dec 07, 1999, Oleg V. Volkov wrote: > > Well, then... > > ``A "sh" command interpreter (shell) ..." should do, I guess... > > Personally, I think it's fine the way it is, or should not be > capitalized at all. The word "A" doesn't belong there. > > Anybody else have any input? I don't like lower-case commands being capitalized in the text if at all possible. It makes it harder for automated man page checking scripts/programs to figure out of the reference is valid. Re-wording the sentence so that the command name doesn't appear at the beginning of the line is the best way. If you have to resort to doing something like: "The sh command does...." Fine. Some people don't like this because sometimes the text reads somewhat stilted depending on the text involved. Other people have also said that we should just capitalized the command name the way it is invoked, even if it is at the start of a line. From various tech writing/manual writing guides I've read, this is frowned upon. I prefer re-wording the sentence so that the command name doesn't appear at the beginning of a line. -Mike -- Mike Pritchard mpp@FreeBSD.org or mpp@mppsystems.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message