> > ... I believe implementation details should not go into man pages
> > either.  man pages should be used for command descriptions, system
> > call API details (library routines, -not- kernel subroutines),

I agree, the man page for ed(4) should give a description of the
black box provided by the if_ed.c driver, but shouldn't be burdened
by internals not of interest to a person running a binary only
release IMHO.

> Why not kernel subroutines?  Section 9 strikes me as a Good Thing.
> Where _would_ you put the kernel-internal interface descriptions?

A section 9 thing is an interesting idea.  I certainly would like to
see such a thing in some form.  Here are some approaches I have seen
toward documenting source code for things like a kernel:

1) The linux groups claims to offer a hypertext tour of the kernel
sources.  This sounds interesting, but I have never embarked on the
tour.  Also in an active system, the sources are a continually moving
target, and such a thing would either have to be frozen to a given
version, which dooms it to obsolescence, or would have to be tied
to the sources so it could move along with them.

2) Knuth has his cweb literate programming system, which is a grand
scheme that would offer the niceties of keeping the sources and its
documention all in a tight package, but trust me, I am not proposing
recoding NetBSD in cweb :-) :-)

3) Good books sometimes do the job well.  I just invested in the
TCP/IP Illustrated, volume 2 which looks like a beautifully done
tour of the TCP/IP code from 4.4BSD-Lite (which is NetBSD as far as
I am concerned).  If I get a year or two, I would like to generate
such a thing for the vm system in NetBSD, or other major subsystems.

4) Then of course we have the approach of simply adding comments
to the sources, and README.scsi files or such like to the source tree,
which I think is the practical approach, and what I really wanted
to suggest when I started all this.  Good documentation needs to
grow along with the sources and be done by the parties involved.
Not that a dedicated and determined individual couldn't generate
something wonderful after the fact (witness the Stevens book above).

> .....  I certainly know back when I was working on the sc
> driver (still am, theoretically, but I haven't touched it in far too
> long) I would have loved to have had a scsi(9) manpage documenting the
> interface(s) provided and required by the /sys/scsi/ subsystem.

I have longed for something like this on the vm system myself.

One of my fond dreams is to get httpd going on my NetBSD machine
and start up a home page that could accumulate assorted NetBSD
lore (as well as other things of potential interest).  Sometimes
good things start small.

The scsi(9) idea is intriguing.

-- 
	Tom Trebisky			Steward Observatory
	ttrebisky@as.arizona.edu	University of Arizona
	(520) 621-5135			Tucson, Arizona 85721