From owner-freebsd-doc Sun Aug 8 12:25:33 1999 Delivered-To: freebsd-doc@freebsd.org Received: from mpp.pro-ns.net (mpp.pro-ns.net [208.200.182.72]) by hub.freebsd.org (Postfix) with ESMTP id 971A114BE6 for ; Sun, 8 Aug 1999 12:25:27 -0700 (PDT) (envelope-from mpp@mpp.pro-ns.net) Received: (from mpp@localhost) by mpp.pro-ns.net (8.9.3/8.9.3) id OAA04233; Sun, 8 Aug 1999 14:23:47 -0500 (CDT) (envelope-from mpp) From: Mike Pritchard Message-Id: <199908081923.OAA04233@mpp.pro-ns.net> Subject: Re: docs/13020: Manpage capitalization In-Reply-To: <199908081400.HAA63051@freefall.freebsd.org> from Tim Vanderhoek at "Aug 8, 1999 07:00:03 am" To: vanderh@ecf.utoronto.ca (Tim Vanderhoek) Date: Sun, 8 Aug 1999 14:23:47 -0500 (CDT) Cc: freebsd-doc@FreeBSD.ORG X-Mailer: ELM [version 2.4ME+ PL54 (25)] MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org > The following reply was made to PR docs/13020; it has been noted by GNATS. > > From: Tim Vanderhoek > To: tomoShige Tashiro > Cc: FreeBSD-gnats-submit@freebsd.org > Subject: Re: docs/13020: Manpage capitalization > Date: Sun, 8 Aug 1999 09:51:18 -0400 > > On Sun, Aug 08, 1999 at 12:46:34PM +0900, tomoShige Tashiro wrote: > > > > I found Capitalized function call 'Putc' in man 3 putc, > > in Feb 1999 (docs/10247) and send-pr and fixed by Mr.hoek. > > They are illegal only when they bother someone... They are always bothersome, because it creates problems with automated man page checking scripts, because now they think you are referencing an undocumented man page. E.g. Putc() prints one character.... Causes some of the automated man page checking scripts to complain because the Putc() function doesn't have a corresponding man page, even though the lower-case putc() man page does exist. The scripts can always suggest that Putc() may really be documented in putc(3), but you can never be sure. It just generates a lot of extra output to wade through to get to the real problems. > > About a half of manpages are written in 2. and 4. > > and last half of manpages are written in 3. > > 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 like to see: The gack() function/command/widget will return... Instead of: The gack() will return... Too many people file PRs about the grammar on the second form. > > But I think, if it's not strange for native English speakers, > > then thats O.K. and no need to fix them. I always try to fix these when I'm working on a man page. > I think we should leave the PR open for about a year (until September, > 2000). If nobody has dealt with it by that time, then it should be > closed ("state: filibustered" :-). I already assigned myself this PR, so it will get dealt with eventually. Sept., 2000 sounds about right :-). The submitter was very helpful, though. He did provide a full list of man pages that do this, so it will help speed my work up. -- Mike Pritchard mpp@FreeBSD.ORG or mpp@mpp.pro-ns.net To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message