Date: Fri, 14 Oct 2005 15:48:32 GMT From: Joe Rhett <jrhett@meer.net> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/87445: comments for improvement of handbook/kernelconfig-config.html Message-ID: <200510141548.j9EFmWpB097536@www.freebsd.org> Resent-Message-ID: <200510141550.j9EFoIsg039092@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 87445 >Category: docs >Synopsis: comments for improvement of handbook/kernelconfig-config.html >Confidential: no >Severity: non-critical >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Fri Oct 14 15:50:18 GMT 2005 >Closed-Date: >Last-Modified: >Originator: Joe Rhett >Release: 5.4 >Organization: meer.net >Environment: >Description: 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 are in the Fix sections below. >How-To-Repeat: >Fix: 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. An example of very clear documentation could be: 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. >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200510141548.j9EFmWpB097536>