From owner-svn-doc-all@FreeBSD.ORG Tue Feb 19 05:48:04 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 77D65B35; Tue, 19 Feb 2013 05:48:04 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-4.mit.edu (DMZ-MAILSEC-SCANNER-4.MIT.EDU [18.9.25.15]) by mx1.freebsd.org (Postfix) with ESMTP id B19DADA4; Tue, 19 Feb 2013 05:48:03 +0000 (UTC) X-AuditID: 1209190f-b7f586d000000915-10-5123120c8a63 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35]) by dmz-mailsec-scanner-4.mit.edu (Symantec Messaging Gateway) with SMTP id 15.6C.02325.C0213215; Tue, 19 Feb 2013 00:47:56 -0500 (EST) Received: from outgoing.mit.edu (OUTGOING-AUTH-1.MIT.EDU [18.9.28.11]) by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id r1J5lugI017897; Tue, 19 Feb 2013 00:47:56 -0500 Received: from multics.mit.edu (SYSTEM-LOW-SIPB.MIT.EDU [18.187.2.37]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r1J5lsIX026490 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Tue, 19 Feb 2013 00:47:55 -0500 Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id r1J5lrxI018676; Tue, 19 Feb 2013 00:47:53 -0500 (EST) Date: Tue, 19 Feb 2013 00:47:53 -0500 (EST) From: Benjamin Kaduk To: Dru Lavigne Subject: Re: svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig In-Reply-To: <201302171741.r1HHf6UX013972@svn.freebsd.org> Message-ID: References: <201302171741.r1HHf6UX013972@svn.freebsd.org> User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrLIsWRmVeSWpSXmKPExsUixCmqrMsjpBxo8OOVhMWPj4eYLLqaVC1u LNrPZLG7v5fZgcVjxqf5LAGMUVw2Kak5mWWpRfp2CVwZCxdcYiyYkFkx5e5ptgbG5oAuRk4O CQETiQUNx5ghbDGJC/fWs3UxcnEICexjlJi44QUzhLORUeLzqcVsIFVCAoeYJHY2GUMkGhgl js87wAqSYBHQlph95zcjiM0moCIx881GsAYRAUWJp1/3gsWZBaIk9ixtBKsXFgiRWNg6lx3E 5hSwktj/eBoLiM0r4CDReGcZ1DJLiRVT74D1igroSKzePwWqRlDi5MwnLBAzLSX+rf3FOoFR cBaS1CwkqQWMTKsYZVNyq3RzEzNzilOTdYuTE/PyUot0TfRyM0v0UlNKNzGCQ1aSfwfjt4NK hxgFOBiVeHg9XJQChVgTy4orcw8xSnIwKYnyCvMpBwrxJeWnVGYkFmfEF5XmpBYfYpTgYFYS 4Q1iBcrxpiRWVqUW5cOkpDlYlMR5r6bc9BcSSE8sSc1OTS1ILYLJynBwKEnwfhAAahQsSk1P rUjLzClBSDNxcIIM5wEafg+khre4IDG3ODMdIn+KUZdjwbVHLxiFWPLy81KlxHl/gBQJgBRl lObBzYGlmleM4kBvCUOM4gGmKbhJr4CWMAEtWXVXEWRJSSJCSqqBUVjmfeO95l9v8ms9mB7r 6D12irn8ROHaMVHx0PeGFdc2b/M52X9qW8+zomM3ZdNrVOPeHNJNvh2x9CKjq+0W9emzitee O7Ii5ajC4a0fu/LPekVzf1t0N1BsR92OE6syzhZlntRq+tokrPHLaVr8AsuPe14fiFW6wXcu 99bCYytFVvTuF174b7MSS3FGoqEWc1FxIgAsyJFsEAMAAA== Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 Feb 2013 05:48:04 -0000 On Sun, 17 Feb 2013, Dru Lavigne wrote: > Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml > ============================================================================== > --- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Sun Feb 17 17:28:26 2013 (r40998) > +++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Sun Feb 17 17:41:05 2013 (r40999) > @@ -281,78 +261,66 @@ following line in &man.loader.conf.5;: > to build the kernel. > > > + The kernel build is located at + class="directory">/usr/src/sys. It contains a The kernel build is at /usr/obj/usr/src/sys/. This should probably refer to the kernel source. > + number of subdirectories representing different parts of the > + kernel. These include + class="directory">arch/conf, > + which contains the kernel configuration file, and > + compile, which is the > + staging area where the kernel will be built. Oof, this is really out of date, probably from 4.X or worse. (The above is probably a symptom of the same problem.) There is no /usr/src/sys/compile directory on modern systems, I think this is a legacy from manually invoking config(8). Of course, I can't easily check, as Eitan has removed all of the bits from the manual for the "old" method of building a kernel. The man page does seem to support this, though. Probably someone should audit the hierarchy described here against a recent kernel build. > + arch contains subdirectories for each > + supported architecture: + class="directory">i386, + class="directory">amd64, + class="directory">ia64, + class="directory">powerpc, + class="directory">sparc64, and + class="directory">pc98. Everything inside a > particular architecture's directory deals with that architecture > - only; the rest of the code is machine independent code common > - to all platforms to which &os; could potentially be ported. > - Notice the logical organization of the directory structure, > - with each supported device, file system, and option in its > - own subdirectory. > - > - The examples in this chapter assume that you are using > - the i386 architecture. If your system has a different > - architecture you need to change the path names > - accordingly. > + only and the rest of the code is machine independent code common > + to all platforms. Notice the logical organization of the > + directory structure, with each supported device, file system, > + and option in its own subdirectory. > + > + The examples in this chapter assume the i386 architecture. > + If the system has a different architecture, change the path > + names accordingly. If we had infinite time, amd64 might be more representative than i386 these days. That said, we have better things to do with our time. > > - If the directory /usr/src/ does not > - exist on your system (or if it is empty), then the sources > - have not been installed. The easiest way to install the full > - source is to use &man.csup.1; as described in - linkend="synching"/>. You should also create a symlink to > + If /usr/src/ does > + not exist or it is empty, source has not been installed. The > + easiest way to install source is to use > + svn as described in + linkend="svn">. One should also create a symlink to I don't agree with using just "source" to describe the system sources; it seems too ambiguous. > /usr/src/sys/: > > &prompt.root; ln -s /usr/src/sys /sys > > > @@ -429,52 +391,49 @@ following line in &man.loader.conf.5;: > > MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs > > - This variable sets up a list of modules to build instead > - of all of them. > + This variable specifies the list of modules to build > + instead the default of building of all of them. This sentence feels a bit awkward ("the default of building of all of them"); I'd prefer "the list of modules to build. The default is to build all modules." or something similar. > @@ -600,37 +550,29 @@ cpu I686_CPU > > ident GENERIC > > - This is the identification of the kernel. You should change > - this to whatever you named your kernel, > - i.e., MYKERNEL > - if you have followed the instructions of the previous examples. > - The value you put in the ident string will > - print when you boot up the kernel, so it is useful to give the > - new kernel a different name if you want to keep it separate > - from your usual kernel (e.g., you want to build an experimental > - kernel). > + This is the identification of the kernel. Change > + this to the new kernel name, such as > + MYKERNEL. > + The value in the ident string will > + print when the kernel boots. I prefer "be printed" to "print". > > > makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols > > - The normal build process of &os; includes > - debugging information when building the kernel with the > - option, which enables debugging > - information when passed to &man.gcc.1;. > + This option enables debugging information when passed to > + &man.gcc.1;. clang handles -g just fine. Maybe we should link to cc(1) which I think changes between gcc and clang with WITH_CLANG_IS_CC? > options SCHED_ULE # ULE scheduler > > @@ -638,17 +580,14 @@ cpu I686_CPU > > options PREEMPTION # Enable kernel thread preemption > > - Allows threads that are in the kernel to be preempted > - by higher priority threads. It helps with interactivity and > - allows interrupt threads to run sooner rather than > - waiting. > + Allows kernel threads to be preempted by higher priority > + threads. This helps with interactivity and allows interrupt > + threads to run sooner rather than waiting. > > options INET # InterNETworking > > - Networking support. Leave this in, even if you do not > - plan to be connected to a network. Most programs require at > - least loopback networking (i.e., making network connections > - within your PC), so this is essentially mandatory. > + Networking support. This is mandatory as most programs > + require at least loopback networking. > > options INET6 # IPv6 communications protocols bz et al may be a bit miffed that INET loopback is mandatory, given their work on INET6-only systems. I don't know that there's a better way to phrase things than what you have, though. > @@ -657,40 +596,38 @@ cpu I686_CPU > options FFS # Berkeley Fast Filesystem > > This is the basic hard drive file system. Leave it in if > - you boot from the hard disk. > + the system boots from the hard disk. Probably "a hard disk", here. > > options SOFTUPDATES # Enable FFS Soft Updates support > > - This option enables Soft Updates in the kernel, this will > - help speed up write access on the disks. Even when this > + This option enables Soft Updates in the kernel which helps > + to speed up write access on the disks. Even when this > functionality is provided by the kernel, it must be turned on > - for specific disks. Review the output from &man.mount.8; to > - see if Soft Updates is enabled for your system disks. If you > - do not see the soft-updates option then you > - will need to activate it using the &man.tunefs.8; (for existing > - file systems) or &man.newfs.8; (for new file systems) > - commands. > + for specific disks. Review the output so &man.mount.8; to SU is per-file-system, not per disk. I'm not sure where the bug in the original came from, but we can fix it here. > + determine if Soft Updates is enabled. If the > + soft-updates option is not in the output, it > + can be activated using &man.tunefs.8; for existing file systems > + or &man.newfs.8; for new file systems. > > @@ -709,9 +646,10 @@ cpu I686_CPU > options NFSSERVER # Network Filesystem Server > options NFS_ROOT # NFS usable as /, requires NFSCLIENT > > - The network file system. Unless you plan to mount > - partitions from a &unix; file server over TCP/IP, you can > - comment these out. > + The network file system (NFS). These > + lines can be commented unless the system needs to mount > + partitions from a NFS file server over > + TCP/IP. NFS works just fine over UDP/IP as well. I don't think there's need to include "over TCP/IP" at all. > > > kernel options > @@ -719,34 +657,32 @@ options NFS_ROOT # NFS > options PROCFS # Process filesystem (requires PSEUDOFS) > > The process file system. This is a pretend I think "pseudo file system" is more of the term of art. > - file system mounted on /proc which allows > - programs like &man.ps.1; to give you more information on what > - processes are running. Use of PROCFS > - is not required under most circumstances, as most > - debugging and monitoring tools have been adapted to run without > - PROCFS: installs will not mount this file > - system by default. > + file system mounted on + class="directory">/proc which allows some programs > + to provide more information on what processes are running. Use > + of PROCFS is not required under most > + circumstances, as most debugging and monitoring tools have been > + adapted to run without PROCFS. The default > + installation will not mount this file system by default. Two uses of "default" in the same sentence; I would probably change the first to "standard". > > options PSEUDOFS # Pseudo-filesystem framework > > @@ -757,51 +693,49 @@ options NFS_ROOT # NFS > > Adds support for url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID > - Partition Tables. GPT provides the ability to have a > - large number of partitions per disk, 128 in the standard > - configuration. > + Partition Tables (GPT. GPT close paren? > + provides the ability to have a large number of partitions per > + disk, 128 in the standard configuration. > [...] > > options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI > > This causes the kernel to pause for 5 seconds before probing > - each SCSI device in your system. If you only have IDE hard > - drives, you can ignore this, otherwise you can try to lower > - this number, to speed up booting. Of course, if you do this > - and &os; has trouble recognizing your SCSI devices, you will > - have to raise it again. > + each SCSI device in the system. If the system only has IDE hard > + drives, ignore this or lower the number to speed up booting. > + However, if &os; has trouble recognizing the SCSI devices, the Spurious "the"? > + number will have to be raised again. Maybe s/number/timeout/? -Ben > > *** DIFF OUTPUT TRUNCATED AT 1000 LINES *** >