Date: Tue, 19 Feb 2013 00:47:53 -0500 (EST) From: Benjamin Kaduk <kaduk@MIT.EDU> To: Dru Lavigne <dru@freebsd.org> Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org Subject: Re: svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig Message-ID: <alpine.GSO.1.10.1302190002310.9389@multics.mit.edu> In-Reply-To: <201302171741.r1HHf6UX013972@svn.freebsd.org> References: <201302171741.r1HHf6UX013972@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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.</para> > </note> > > + <para>The kernel build is located at <filename > + class="directory">/usr/src/sys</filename>. 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 <filename > + class="directory"><replaceable>arch</replaceable>/conf</filename>, > + which contains the kernel configuration file, and > + <filename class="directory">compile</filename>, 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. > + <replaceable>arch</replaceable> contains subdirectories for each > + supported architecture: <filename > + class="directory">i386</filename>, <filename > + class="directory">amd64</filename>, <filename > + class="directory">ia64</filename>, <filename > + class="directory">powerpc</filename>, <filename > + class="directory">sparc64</filename>, and <filename > + class="directory">pc98</filename>. 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.</para> > - > - <para>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.</para> > + 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.</para> > + > + <para>The examples in this chapter assume the i386 architecture. > + If the system has a different architecture, change the path > + names accordingly.</para> 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. > <note> > - <para>If the directory <filename>/usr/src/</filename> 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 <xref > - linkend="synching"/>. You should also create a symlink to > + <para>If <filename class="directory">/usr/src/</filename> does > + not exist or it is empty, source has not been installed. The > + easiest way to install source is to use > + <application>svn</application> as described in <link > + linkend="svn"></link>. One should also create a symlink to I don't agree with using just "source" to describe the system sources; it seems too ambiguous. > <filename class="directory">/usr/src/sys/</filename>:</para> > > <screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen> > </note> > > @@ -429,52 +391,49 @@ following line in &man.loader.conf.5;: > > <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting> > > - <para>This variable sets up a list of modules to build instead > - of all of them.</para> > + <para>This variable specifies the list of modules to build > + instead the default of building of all of them.</para> 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</programlisting> > > <programlisting>ident GENERIC</programlisting> > > - <para>This is the identification of the kernel. You should change > - this to whatever you named your kernel, > - i.e., <literal><replaceable>MYKERNEL</replaceable></literal> > - if you have followed the instructions of the previous examples. > - The value you put in the <literal>ident</literal> 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).</para> > + <para>This is the identification of the kernel. Change > + this to the new kernel name, such as > + <literal><replaceable>MYKERNEL</replaceable></literal>. > + The value in the <literal>ident</literal> string will > + print when the kernel boots.</para> I prefer "be printed" to "print". > <!-- XXX: Add a comment here that explains when compiling hints into > the kernel is a good idea and why. --> > > <programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting> > > - <para>The normal build process of &os; includes > - debugging information when building the kernel with the > - <option>-g</option> option, which enables debugging > - information when passed to &man.gcc.1;.</para> > + <para>This option enables debugging information when passed to > + &man.gcc.1;.</para> 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? > <programlisting>options SCHED_ULE # ULE scheduler</programlisting> > > @@ -638,17 +580,14 @@ cpu I686_CPU</programlisting> > > <programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting> > > - <para>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.</para> > + <para>Allows kernel threads to be preempted by higher priority > + threads. This helps with interactivity and allows interrupt > + threads to run sooner rather than waiting.</para> > > <programlisting>options INET # InterNETworking</programlisting> > > - <para>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.</para> > + <para>Networking support. This is mandatory as most programs > + require at least loopback networking.</para> > > <programlisting>options INET6 # IPv6 communications protocols</programlisting> 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</programlisting> > <programlisting>options FFS # Berkeley Fast Filesystem</programlisting> > > <para>This is the basic hard drive file system. Leave it in if > - you boot from the hard disk.</para> > + the system boots from the hard disk.</para> Probably "a hard disk", here. > > <programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting> > > - <para>This option enables Soft Updates in the kernel, this will > - help speed up write access on the disks. Even when this > + <para>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 <literal>soft-updates</literal> 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.</para> > + 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 > + <literal>soft-updates</literal> 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.</para> > > @@ -709,9 +646,10 @@ cpu I686_CPU</programlisting> > options NFSSERVER # Network Filesystem Server > options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting> > > - <para>The network file system. Unless you plan to mount > - partitions from a &unix; file server over TCP/IP, you can > - comment these out.</para> > + <para>The network file system (<acronym>NFS</acronym>). These > + lines can be commented unless the system needs to mount > + partitions from a <acronym>NFS</acronym> file server over > + TCP/IP.</para> NFS works just fine over UDP/IP as well. I don't think there's need to include "over TCP/IP" at all. > > <indexterm> > <primary>kernel options</primary> > @@ -719,34 +657,32 @@ options NFS_ROOT # NFS > <programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting> > > <para>The process file system. This is a <quote>pretend</quote> I think "pseudo file system" is more of the term of art. > - file system mounted on <filename>/proc</filename> which allows > - programs like &man.ps.1; to give you more information on what > - processes are running. Use of <literal>PROCFS</literal> > - is not required under most circumstances, as most > - debugging and monitoring tools have been adapted to run without > - <literal>PROCFS</literal>: installs will not mount this file > - system by default.</para> > + file system mounted on <filename > + class="directory">/proc</filename> which allows some programs > + to provide more information on what processes are running. Use > + of <literal>PROCFS</literal> is not required under most > + circumstances, as most debugging and monitoring tools have been > + adapted to run without <literal>PROCFS</literal>. The default > + installation will not mount this file system by default.</para> Two uses of "default" in the same sentence; I would probably change the first to "standard". > > <programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting> > > @@ -757,51 +693,49 @@ options NFS_ROOT # NFS > > <para>Adds support for <ulink > url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID > - Partition Tables</ulink>. GPT provides the ability to have a > - large number of partitions per disk, 128 in the standard > - configuration.</para> > + Partition Tables</ulink> (<acronym>GPT</acronym>. GPT close paren? > + provides the ability to have a large number of partitions per > + disk, 128 in the standard configuration.</para> > [...] > > <programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting> > > <para>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.</para> > + 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.</para> Maybe s/number/timeout/? -Ben > > *** DIFF OUTPUT TRUNCATED AT 1000 LINES *** >
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.GSO.1.10.1302190002310.9389>