# HG changeset patch
# User Rob Landley <rob@landley.net>
# Date 1194500572 21600
# Node ID ac8a8db09cd1c8629235fa96d6c856e83cd8339c
# Parent  41f999d7f077e1f3f49027dd5e82d129c036d432
Fluff out master.idx still more.

diff -r 41f999d7f077 -r ac8a8db09cd1 master.idx
--- a/master.idx	Wed Nov 07 23:42:08 2007 -0600
+++ b/master.idx	Wed Nov 07 23:42:52 2007 -0600
@@ -28,11 +28,17 @@
 <p>These are various upstream sources of documentation, many of which are linked
 into the <a href=http://kernel.org/doc>linux kernel documentation index</a>.</p>
 
+<span id="From the kernel">
 <ul>
 <li><a href=Documentation>Text files in the kernel's Documentation directory.</a></li>
 <li><a href=htmldocs>Output of kernel's "make htmldocs".</a></li>
 <li><a href=menuconfig>Menuconfig help</a></li>
 <li><a href=readme>Linux kernel README files</a></li>
+<li><a href=rfc-linux.html>IETF RFCs referred to by kernel source files.</a></li>
+</ul>
+</span>
+<span id="Out on the web">
+<ul>
 <li><a href=xmlman>html version of man-pages package</a></li>
 <li><a href=http://lwn.net/Kernel/Index/>Linux Weekly News kernel articles</a></li>
 <li>Linux Device Drivers book (<a href=http://lwn.net/Kernel/LDD3/>third edition</a>) (<a href=http://www.xml.com/ldd/chapter/book/>second edition</a>)</li>
@@ -45,6 +51,7 @@
 <li><a href=video.html>Selected videos of interest</a></li>
 <li><a href=local>Some locally produced docs</a></li>
 </ul>
+</span>
 
 <span id="Standards">
 <ul>
@@ -74,6 +81,16 @@
 with the command "make", and installed either manually or with the command
 "make install".</p>
 
+<blockquote>
+<pre>
+tar xvjf linux-2.6.??.tar.bz2
+cd linux-2.6.??
+make menuconfig
+make
+make install
+</pre>
+</blockquote>
+
 <p>For a description of the make options and targets, type <a href=makehelp.txt>
 make help</a>.</p>
 
@@ -97,17 +114,74 @@
 command "make distclean".</p>
 </span>
 
-    <span id="Configuring">
+<span id="Configuring">
+
+<p>Before you can build the kernel, you have to configure it.  Configuring
+selects which features this kernel build should include, and specifies other
+technical information such as buffer sizes and optimization strategies.
+This information is stored in a file named ".config" in the top level directory
+of the kernel source code.  To see the various user interfaces to the
+configuration system, type "<a href=makehelp.txt>make help</a>".</p>
+
+<p>Note that "make clean" does not delete configuration information, but the
+more thorough "make distclean" does.</p>
+
+<span id="Using an existing configuration">
+
+<p>Often when building a kernel, an existing .config file is supplied from
+elsewhere.  Copy it into place, and optionally run "make oldconfig" to run
+the kernel's diagnostics against it to ensure it matches the kernel version
+you're using, updating anything that's out of sync.</p>
+
+<p>Several preset configurations are shipped with the kernel source code.
+Run the command <b>find . -name "*_defconfig"</b> in the kernel source
+directory to seem them all.  Any of these can be copied to .config and
+used as a starting point.</p>
 
-<p>The Linux configuration system is called <a href=Documentation/kconfig-language.txt>Kconfig</a>.
-The most common user interface for kconfig is menuconfig, an interactive terminal based menuing
-interface invoked through the makefiles via "<b>make menuconfig</b>".  A simpler text based
-question and answer interface (which does not require curses support or a tty) is available as
-"<b>make config</b>".  Graphical interfaces are available as "<b>make xconfig</b>" (based on QT)
-and "<b>make gconfig</b>" (based on GTK).  For more information, see
-<a href=makehelp.txt>make help</a></p>
+<p>The kernel can also automatically generate various configurations,
+mostly to act as starting points for customization:</p>
+<ul>
+<li><b>make defconfig</b> - Set all options to default values</li>
+<li><b>make allnoconfig</b> - Set all yes/no options to "n"</li>
+<li><b>make allyesconfig</b> - Set all yes/no options to "y"</li>
+<li><b>make allmodconfig</b> - Set all yes/no options to "y" and all "yes/module/no" options to "m"</li>
+<li><b>make randconfig</b> - Set each option randomly (for debugging purposes).</li>
+<li><b>make oldconfig</b> - Update a .config file from a previous version of the kernel to work with the current version.</li>
+</ul>
+
+</span>
+<span id="Creating a custom kernel configuration">
+<p>The most common user interface for configuring the kernel is
+<b>menuconfig</b>, an interactive terminal based menuing interface invoked
+through the makefiles via "<b>make menuconfig</b>".  This interface groups the
+configuration questions into a series of menus, showing the current values
+of each symbol and allowing them to be changed in any order.  Each symbol
+has associated help text, explaining what the symbol does and where to find
+more information about it.  This help text is
+<a href=menuconfig>also available as html</a>.</p>
 
-<p>The configuration interfaces present 
+<p>The menuconfig interface is controlled with the following keys:</p>
+
+<ul>
+<li><b>cursor up/down</b> - move to another symbol</li>
+<li><b>tab</b> - switch action between edit, help, and exit</li>
+<li><b>enter</b> - descend into menu (or help/exit if you hit tab first)</li>
+<li><b>esc</b> - exit menu (prompted to save if exiting top level menu)</li>
+<li><b>space</b> - change configuration symbol under cursor</li>
+<li><b>?</b> - view help for this symbol</li>
+<li><b>/</b> - search for a symbol by name</li>
+</ul>
+
+<p>Other configuration interfaces (functionally equivalent to menuconfig)
+include:</p>
+<ul>
+<li><b>make config</b> - a simple text based question and answer interface
+(which does not require curses support, or even a tty)</li>
+<li><b>make xconfig</b> - QT based graphical interface</li>
+<li><b>make gconfig</b> - GTK based graphical interface</li>
+</ul>
+
+</span>
 
     </span>
     <span id="building">
@@ -174,6 +248,16 @@
   </span>
   <span id="Infrastructure">
     <span id="kconfig">
+<p>The Linux configuration system is called Kconfig.  The various
+configuration front-ends (such as menuconfig) parse data files
+written in the <a href=Documentation/kconfig-language.txt>Kconfig language</a>,
+which define the available symbols and provide default values, help entries,
+and so on.</p>
+
+<p>The source code for the front ends is in scripts/kconfig.  The
+Makefile in this directory defines the make targets for the configuration
+system.</p>
+
     </span>
     <span id="kbuild">
     </span>
@@ -438,7 +522,8 @@
 <a href=http://lwn.net/Articles/250967/>one</a>,
 <a href=http://lwn.net/Articles/252125/>two</a>,
 <a href=http://lwn.net/Articles/253361/>three</a>,
-<a href=http://lwn.net/Articles/254445/>four</a>.
+<a href=http://lwn.net/Articles/254445/>four</a>,
+<a href=http://lwn.net/Articles/255364/>five</a>.
 </li>
     <li>Ars technica ram guide, article series by Jon "Hannibal" Stokes, parts
 <a href=http://arstechnica.com/paedia/r/ram_guide/ram_guide.part1-1.html>one</a>,