comments for improvement of handbook/kernelconfig-config.html

[Joe Rhett]

http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig- 
config.html

I'd like to offer some quick comments, after spending several hours  
reading and googling only to verify the fairly obvious but that wasn't  
spelled out.  My comments to improve this page include

1.  Start the beginning.  What does the kernel configuration file do?   
If the following statement is true, let's put this (or something  
similar) somewhere near the top:

	"The kernel configuratioon file defines the modules which will be  
built statically into the kernel.  You would change this file to remove  
modules from your kernel, or to change some kernel options. It does not  
limit or prevent you from adding dynamically loadable modules later.   
If you want to include a loadable module in your kernel, you don't need  
to rebuild your kernel configuration."

This appears to be true, and running several kernel builds appears to  
prove it, but just determining whether or not it was true was downright  
difficult.

2. Move the comment about NOTES/LINT to the bottom.  It's unlikely that  
your average kernel builder would care about most of this stuff, and  
they should read to the bottom anyway.  It's kindof "if we didn't talk  
about it here..." kind of comment anyway.  It certainly confuses the  
subject when you first hit this page.

3. Identify which modules are required for a kernel to boot.  Or have  
some discussion of this.  And in general -- what does it mean when I  
remove a module?  Can I remove plip from the kernel but have it  
installed as a .ko so that I can load it dynamically later on if by  
some reason I decide to use it?  What's the limitations of this  
approach?

And lastly, stop with the intertwined 4.x and 5.x (and soon 6.x)  
comments.  If there are different answers, put them in separate blocks.  
  Maybe color them separately.  It's incredibly frustrating to go  
through a paragraph and then hit an else near the end that makes you  
wonder just how many statements before the else are being negated.

> device   gif           # IPv6 and IPv4 tunneling
>
> This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,  
> IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with  
> FreeBSD 4.4 the gif device is “auto-cloning”, and you should use the  
> line pseudo-device gif. Earlier versions of FreeBSD 4.X require a  
> number, for example pseudo-device gif 4.

Huh?  What?  Did I read this right?  Instead, why not:

> FreeBSD 5/6:
> device   gif           # IPv6 and IPv4 tunneling
>
> FreeBSD 4.4 and above:
> pseudo-device   gif           # IPv6 and IPv4 tunneling
>
> FreeBSD 4.3 and earlier:
> pseudo-device   gif   4        # the number of IPv6 and IPv4 tunneling  
> interfaces
>
> This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,  
> IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with  
> FreeBSD 4.4 the gif device is “auto-cloning”. Earlier versions of  
> FreeBSD 4.X require a number, for example pseudo-device gif 4.


-- 
Joe Rhett
senior geek
svcolo : meer.net