Date: Sun, 8 Aug 1999 14:23:47 -0500 (CDT) From: Mike Pritchard <mpp@mpp.pro-ns.net> To: vanderh@ecf.utoronto.ca (Tim Vanderhoek) Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/13020: Manpage capitalization Message-ID: <199908081923.OAA04233@mpp.pro-ns.net> In-Reply-To: <199908081400.HAA63051@freefall.freebsd.org> from Tim Vanderhoek at "Aug 8, 1999 07:00:03 am"
next in thread | previous in thread | raw e-mail | index | archive | help
> The following reply was made to PR docs/13020; it has been noted by GNATS.
>
> From: Tim Vanderhoek <vanderh@ecf.utoronto.ca>
> To: tomoShige Tashiro <shige2@pop17.odn.ne.jp>
> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199908081923.OAA04233>