From owner-freebsd-doc Mon Oct 29 12:46: 0 2001 Delivered-To: freebsd-doc@freebsd.org Received: from lists.blarg.net (lists.blarg.net [206.124.128.17]) by hub.freebsd.org (Postfix) with ESMTP id BFB1437B406 for ; Mon, 29 Oct 2001 12:45:57 -0800 (PST) Received: from thig.blarg.net (thig.blarg.net [206.124.128.18]) by lists.blarg.net (Postfix) with ESMTP id 1ABD1BD11; Mon, 29 Oct 2001 12:45:57 -0800 (PST) Received: from localhost.localdomain ([206.124.139.115]) by thig.blarg.net (8.9.3/8.9.3) with ESMTP id MAA10444; Mon, 29 Oct 2001 12:45:56 -0800 Received: (from jojo@localhost) by localhost.localdomain (8.11.6/8.11.3) id f9TKiiq50620; Mon, 29 Oct 2001 12:44:44 -0800 (PST) (envelope-from swear@blarg.net) To: setantae Cc: FreeBSD-doc@FreeBSD.ORG Subject: Re: Capitalisation of program names References: <20011029123803.A14177@rhadamanth> From: swear@blarg.net (Gary W. Swearingen) Date: 29 Oct 2001 12:44:43 -0800 In-Reply-To: <20011029123803.A14177@rhadamanth> Message-ID: <82g082fa6c.082@localhost.localdomain> Lines: 30 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org You want opinions; I got opinions. Yes, it's a religious thing and has been discussed before. The "man" manual page says that "Man" does such-and-such. That's just wrong. It's also ugly, especially when the formatter (eg, Emacs' "man" command) doesn't use bold type or quotes for names. It's also unecessary. In most cases, one could just say "This command ..." or even just "This ..."; in other cases "The 'man' command ..." is very little harder to write and shouldn't cause nearly as many readers to stumble at the inaccuracy and ugliness at the negligable cost of a split second longer to read two extra words. Starting a sentence with a lower case letter is formally bad English, but might be tolerable if bold type could be guaranteed -- which it cannot (eg, in Emacs' man command). It's bad enough at the start of paragraphs, but when done mid-paragraph, after a proper sentence, it's even worse. > whilst these uppercase the name if it appears at the start of the > sentence: The "Man" command was omitted. > All other manpages skirt round the issue by saying something like: > The rm utility... In case of the first sentence of the "Description", I would change them ALL to "This command|function|whatever...", except where the man page documents multiple things. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message