Subject: Re: man pages & style guide
To: None <current-users@NetBSD.ORG>
From: der Mouse <mouse@Collatz.McRCIM.McGill.EDU>
List: current-users
Date: 03/07/1996 06:58:34
> It has always seemed to me than maybe man should save the
> preformatted version everytime it is invoked on an unformatted page..

All the non-NetBSD mans I have used do this.  (I say "non-NetBSD"
because I don't recall man ever having to format a manpage under
NetBSD, because it installs preformatted manpages.)  The presence of
both man* and cat* directories in /usr/share/man makes me think
NetBSD's man is capable of doing this too.  I take it you don't see it
happening?  Are you sure the user you're running man as can write to
the cat* directory?

> But why do we dislike ANSI function definitions, with parameter types
> in the arglist??

This is a bit of a religious issue.  The theory seems to be that we
want NetBSD to be buildable with compilers that don't support
prototypes.

Personally, I think this is pointless.  It's hard to imagine wanting to
port to a machine that doesn't support gcc; it's even harder to imagine
such a machine that doesn't already have a prototype-capable compiler.

> Also, although I feel much less strongly about this, why do we not
> named parameters in prototypes?

It pollutes the user's namespace.  If the header file says, for
example (after __P expansion)

	ssize_t read(int d, void *buf, size_t nbytes);

then if the user happens to have said

	#define nbytes 10240

before including the file, it will break.  But "nbytes" is in the
user's namespace; there is no excuse for gratuitously hijacking a whole
bunch of perfectly useful names.

> I always feel this makes header files nicely self-documenting...

True.  But so would

	ssize_t read(int /*d*/, void * /*buf*/, size_t /*nbytes*/);

and it wouldn't step on d, buf, and nbytes.

					der Mouse

			    mouse@collatz.mcrcim.mcgill.edu