Subject: re: bin/7249
To: Erik E. Fair <email@example.com>
From: Chuck McManis <firstname.lastname@example.org>
Date: 07/15/2000 14:41:30
This is the "spec" vs "guide" arguement.
On the "spec" side, the argument goes something like this:
"The man pages are the specification for the system, by making them
exhaustively complete one can insure compliance through testing to
the agreed upon standard. This aids interoperability and
amongst different implementations."
On the "guide" side, the argument goes something like this:
"The man pages are a guide for the programmer who is using the
system. They help him or her to write programs that will run
under the system and identify the most common error conditions
that might prevent the program from running. For really
complex errors the source is always available."
Having had some experience at Sun on the "spec" side of the argument I can
assure you that the NetBSD project doesn't have nearly enough resources to
maintain a NetBSD specification. Therefore, unless you can do this for all
man pages (ie spec mode) then it will be no better than guide mode, thus
I'm going to suggest that the answer is guide mode.
In that mode it is important to cover the error conditions that are most
likely to occur and to reference the definitive documentation (ie the
source). So perhaps a good compromise would be a new MAN section
"IMPLEMENTED IN" which identifies where in the source tree you can find the
At 10:57 AM 7/15/00 -0700, Erik E. Fair wrote:
>The PR wants every error that a given system call can return in the man
>page for that system call (in section 2). I'm asking for discussion here
>as to whether that's reasonable (it is gonna be a maintenance headache,
>unless we find some automated way to produce it from the code paths).
> Erik <email@example.com>