Date: Mon, 24 Jun 2002 23:45:37 -0400 (EDT) From: Chris Pepper <pepper@rockefeller.edu> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/39824: Various tweaks for doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml; corresponding comment clarification for GENERIC Message-ID: <20020625034537.7BF6DA827@guest.reppep.com>
next in thread | raw e-mail | index | archive | help
>Number: 39824
>Category: docs
>Synopsis: Various tweaks for doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml; corresponding comment clarification for GENERIC
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Jun 24 20:50:01 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator: Chris Pepper
>Release: FreeBSD 4.6-STABLE i386
>Organization:
>Environment:
System: FreeBSD guest.reppep.com 4.6-STABLE FreeBSD 4.6-STABLE #0: Tue Jun 18 21:27:59 EDT 2002 pepper@guest.reppep.com:/usr/obj/usr/src/sys/GENERIC i386
>Description:
Misc linguistic tweaks.
Clarify description of /usr/src/UPDATING
Change <quote>traditional</quote> adjective for kernel builds to old; change <quote>new</quote> to new.
Change "The Configuration File" to "The Kernel Configuration File" (it's not the only config file!).
procfs is a real filesystem, that doesn't hold actual on-disk data files.
Mention that ptys are used for ssh.
The vpo option's comment in GENERIC should mention it's for Zip drives; this patch includes both a patch to the quoted line for chapter.sgml, and a patch for GENERIC as well.
>How-To-Repeat:
Read doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml & /usr/src/sys/i386/conf/GENERIC.
>Fix:
Two patches follow.
--- chapter.sgml.diff begins here ---
Index: chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml,v
retrieving revision 1.76
diff -u -r1.76 chapter.sgml
--- chapter.sgml 2002/05/04 14:22:35 1.76
+++ chapter.sgml 2002/06/25 03:34:16
@@ -77,7 +77,7 @@
<para>Traditionally, FreeBSD has had what is called a
<quote>monolithic</quote> kernel. This means that the kernel was one
- large program, supported a fixed list of devices, and if you wanted to
+ large program, which supported a fixed list of devices, and if you wanted to
change the kernel's behavior then you had to compile a new kernel, and
then reboot your computer with the new kernel.</para>
@@ -120,7 +120,7 @@
<listitem>
<para>Additional hardware support. A custom kernel allows you to
- add in support for devices such as sound cards, which are not
+ add in support for devices such as sound cards which are not
present in the <literal>GENERIC</literal> kernel.</para>
</listitem>
</itemizedlist>
@@ -231,15 +231,11 @@
section slowly and carefully.</para>
<note>
- <para>Be sure to always check the file
- <filename>/usr/src/UPDATING</filename>, before you perform any update
- steps, in the case you <link
- linkend="cutting-edge">sync your source-tree</link> with the
- latest sources of the FreeBSD project.
- In this file all important issues with updating FreeBSD
- are written down. <filename>/usr/src/UPDATING</filename> always fits
- to your version of the FreeBSD source, and is therefore more accurate
- for those information than the handbook.</para>
+ <para>If you <link linkend="cutting-edge">update your FreeBSD source</link>, be sure to check the file
+ <filename>/usr/src/UPDATING</filename>.
+ This file mentions important issues you should be aware of when working with updated FreeBSD source code. <filename>/usr/src/UPDATING</filename> always tracks
+ your version of the FreeBSD source, and is therefore more up to date
+ for your system than the handbook.</para>
</note>
<para>You must now compile the source code for the kernel. There are two
@@ -274,7 +270,7 @@
</itemizedlist>
<procedure>
- <title>Procedure 1. Building a kernel the <quote>traditional</quote> way</title>
+ <title>Procedure 1. Building a kernel the old way</title>
<step>
<para>Run &man.config.8; to generate the kernel source code.</para>
@@ -303,7 +299,7 @@
</procedure>
<procedure>
- <title>Procedure 2. Building a kernel the <quote>new</quote>
+ <title>Procedure 2. Building a kernel the new
way</title>
<step>
@@ -343,7 +339,7 @@
</indexterm>
<para>If you have <emphasis>not</emphasis> upgraded your source
- tree in any way (you have not run <application>CVSup</application>,
+ tree in any way (you have not run <application>CVSup</application> or
<application>CTM</application>, or used
<application>anoncvs</application>), then you should use the
<command>config</command>, <maketarget>make depend</maketarget>,
@@ -373,7 +369,7 @@
</sect1>
<sect1 id="kernelconfig-config">
- <title>The Configuration File</title>
+ <title>The Kernel Configuration File</title>
<indexterm>
<primary>kernel</primary>
<secondary>LINT</secondary>
@@ -384,7 +380,7 @@
<secondary>config file</secondary>
</indexterm>
- <para>The general format of a configuration file is quite simple.
+ <para>The general format of a kernel configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a <literal>#</literal> is considered a comment and
@@ -516,10 +512,10 @@
<para>Starting with FreeBSD 4.5, the system will auto-tune this setting
for you if you explicitly set it to <literal>0</literal><footnote>
<para>The auto-tuning algorithm sets <literal>maxuser</literal> equal
- to the amount of memory in the system, with a minimum of 32, and a
+ to the number of megabytes of memory in the system, with a minimum of 32, and a
maximum of 384.</para></footnote>. If you are
using an earlier version of FreeBSD, or you want to manage it
- yourself you will want to set
+ yourself, you will want to set
<literal>maxusers</literal> to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by <literal>maxusers</literal> is the
@@ -540,8 +536,8 @@
<note>
<para><literal>maxusers</literal> does <emphasis>not</emphasis>
- limit the number of users which can log into your machine. It
- simply sets various table sizes to reasonable values considering
+ limit the number of users who can log into your machine. It
+ simply sets various table sizes to reasonable values based on
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which <emphasis>does</emphasis> limit the number of simultaneous
@@ -607,7 +603,7 @@
<programlisting>options UFS_DIRHASH #Improve performance on big directories</programlisting>
<para>This option includes some code to speed up disk operations on large
- directories, at the expense of using a some additional memory. You
+ directories, at the expense of using some additional memory. You
would normally keep this for a large server, or interactive workstation,
and remove it if you are using FreeBSD on a smaller system where memory
is at a premium and disk access speed is less important, such as a
@@ -615,11 +611,11 @@
<programlisting>options SOFTUPDATES #Enable FFS soft updates support</programlisting>
- <para>This option enables soft updates in the kernel, this will help speed
+ <para>This option enables soft updates in the kernel; this will help speed
up write access on the disks. They are enabled by default in the 4.X branch
but may not be turned on. Review the output from &man.mount.8; to see
if you have them enabled. If you do not see the soft-updates option then
- you will need to activate it using the &man.tunefs.8; or &man.newfs.8;
+ you may activate it using &man.tunefs.8; or &man.newfs.8;
for new filesystems.</para>
<programlisting>options MFS #Memory Filesystem
@@ -680,7 +676,7 @@
<programlisting>options PROCFS #Process filesystem</programlisting>
- <para>The process filesystem. This is a <quote>pretend</quote>
+ <para>The process filesystem. This is a special
filesystem mounted on <filename>/proc</filename> which allows
programs like &man.ps.1; to give you more information on what
processes are running.</para>
@@ -688,7 +684,7 @@
<programlisting>options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
<para>Compatibility with 4.3BSD. Leave this in; some programs will
- act strangely if you comment this out.</para>
+ behave strangely if you comment this out.</para>
<programlisting>options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI</programlisting>
@@ -697,14 +693,14 @@
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
- you will have to raise it back up.</para>
+ you will have to raise it again.</para>
<programlisting>options UCONSOLE #Allow users to grab the console</programlisting>
<para>Allow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing <command>xterm
-C</command>, which will display any <command>write</command>,
- <command>talk</command>, and any other messages you receive, as well
+ <command>talk</command>, and other messages you receive, as well
as any console messages sent by the kernel.</para>
<programlisting>options USERCONFIG #boot -c editor</programlisting>
@@ -748,7 +744,7 @@
<programlisting>options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULING</programlisting>
- <para>Real-time extensions added in the 1993 POSIX. Certain
+ <para>Real-time extensions added in the 1993 POSIX specification. Certain
applications in the ports collection use these
(such as <application>StarOffice</application>).</para>
@@ -763,7 +759,7 @@
<para>This option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
- denial of service packet attacks.</para>
+ ICMP denial of service attacks.</para>
<indexterm>
<primary>kernel options</primary>
@@ -777,9 +773,9 @@
<programlisting>device isa</programlisting>
- <para>All PCs supported by FreeBSD have one of these. If you have an
+ <para>All PCs supported by FreeBSD have ISA. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
- this time (support is being worked on).</para>
+ this time (support is in development).</para>
<programlisting>device eisa</programlisting>
@@ -790,7 +786,7 @@
<programlisting>device pci</programlisting>
<para>Include this if you have a PCI motherboard. This enables
- auto-detection of PCI cards and gatewaying from the PCI to ISA
+ auto-detection of PCI cards and gatewaying from the PCI to the ISA
bus.</para>
<programlisting># Floppy drives
@@ -832,8 +828,8 @@
<programlisting>options ATA_STATIC_ID #Static device numbering</programlisting>
- <para>This makes the controller number static (like the old driver) or
- else the device numbers are dynamically allocated.</para>
+ <para>This makes the ATA controller number static (like the old driver);
+ otherwise the device numbers are dynamically allocated.</para>
<programlisting># ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
@@ -890,7 +886,7 @@
<programlisting>device atkbd0 at atkbdc? irq 1</programlisting>
- <para>The <literal>atkbd</literal> driver, together with
+ <para>The <literal>atkbd</literal> driver, together with the
<literal>atkbdc</literal> controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.</para>
@@ -965,14 +961,14 @@
<note>
<para>If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
- obscure technical reasons, IRQ2 = IRQ 9) in order to access it
+ obscure technical reasons, IRQ 2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
- S3 chips) use IO addresses in the form of
+ S3 chipsets) use IO addresses in the form of
<literal>0x*2e8</literal>, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
- these cards making the COM4 port practically unavailable.</para>
+ these cards, making the COM4 port effectively unavailable.</para>
<para>Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
@@ -983,7 +979,7 @@
<programlisting># Parallel port
device ppc0 at isa? irq 7</programlisting>
- <para>This is the ISA-bus parallel port interface.</para>
+ <para>This is the ISA bus parallel port interface.</para>
<programlisting>device ppbus # Parallel port bus (required)</programlisting>
@@ -1007,7 +1003,7 @@
<para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
I/O.</para>
- <programlisting>#device vpo # Requires scbus and da</programlisting>
+ <programlisting>#device vpo # Zip support; requires scbus and da</programlisting>
<indexterm><primary>zip drive</primary></indexterm>
<para>This is for an Iomega Zip drive. It requires
@@ -1109,7 +1105,7 @@
pseudo-device pty # Pseudo-ttys (telnet etc)</programlisting>
<para>This is a <quote>pseudo-terminal</quote> or simulated login port.
- It is used by incoming <command>telnet</command> and
+ It is used by incoming <command>ssh</command>, <command>telnet</command>, and
<command>rlogin</command> sessions,
<application>xterm</application>, and some other applications such
as <application>emacs</application>. A
@@ -1148,14 +1144,14 @@
<para>This is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an Ethernet). These packets
- can be captured to disk and or examined with the &man.tcpdump.1;
+ can be captured to disk and/or examined with the &man.tcpdump.1;
program.</para>
<note>
<para>The <literal>bpf pseudo-device</literal> is also used by
&man.dhclient.8; to obtain the IP address of the default router
(gateway) and so on. If you use DHCP, leave this
- uncommented.</para>
+ enabled.</para>
</note>
<programlisting># USB support
--- chapter.sgml.diff ends here ---
--- GENERIC Mon Jun 24 23:32:58 2002
+++ GENERIC.fixed Mon Jun 24 23:33:24 2002
@@ -169,7 +169,7 @@
device lpt # Printer
device plip # TCP/IP over parallel
device ppi # Parallel port interface device
-#device vpo # Requires scbus and da
+#device vpo # Iomega Zip drive: requires scbus and da
# PCI Ethernet NICs.
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020625034537.7BF6DA827>