Re: CVS commit: src/sys/fs/tmpfs

[Jim Wise <jwise%draga.com@localhost>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Tue, 13 Sep 2005, Perry E. Metzger wrote:

>I have to say I disagree. Often, in trying to debug one portion of the
>kernel or another, it is VERY valuable to understand the inside of how
>that portion of the kernel works. The 4.4 book is pretty old at this
>point and was woefully incomplete.

I don't see a problem with keeping such documents, but it strikes me 
that putting them in manual section 9 is an overloading of the meaning 
of that section.

If I am looking for a kernel API to do something in a driver, lkm, or 
kernel change, and keep seeing promising-looking man pages which turn 
out to be false leads as they document internal workings with no visible 
(and thus usable) API, I'm likely to get frustrated.

This doesn't mean we shouldn't keep such documentation, but I think it 
_does_ mean such documents should go either in /usr/share/doc (my 
preference), manual section 4 (perfectly reasonable) or in a new man 
section.


>Surely you don't think less documentation is better than more?

That rather depends on context.  The various sections of the unix manual 
were originally created so a user looking for a command to use would not 
be swamped by dozens of entries for similar-sounding library APIs which 
were of no use to him (`more documentation' though such entries might, 
indeed, be).  I think the same applies here, certainly.

- -- 
                                Jim Wise
                                jwise%draga.com@localhost
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (NetBSD)

iD8DBQFDJyzOpRpI6SYACmIRAuAfAKCE2yvz18hlPvVEiUvs1yx4E1eucACdHk+u
6mT8UfkPJdUPEy5Co0+RE74=
=D5Yt
-----END PGP SIGNATURE-----