Trunk is now identical to Testing

git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@4648 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689

36 files changed, 1585 insertions, 181 deletions

diff --git a/chapter05/adjusting.xml b/chapter05/adjusting.xml
index ac342fe87..834ef166f 100644
--- a/chapter05/adjusting.xml
+++ b/chapter05/adjusting.xml
@@ -7,12 +7,34 @@
 <title>Adjusting the Toolchain</title>
 <?dbhtml filename="adjusting.html"?>
 
-<para>Run the following command from within
-the <filename class="directory">binutils-build</filename> directory:</para>
+<para>Now that the temporary C libraries have been installed, all
+tools compiled in the rest of this chapter should be linked against
+these libraries. In order to accomplish this, the linker and the
+compiler's specs file need to be adjusted.</para>
+
+<para>The linker, adjusted at the end of the first pass of Binutils,
+is installed by running the following command from within the
+<filename class="directory">binutils-build</filename> directory:</para>
 
 <screen><userinput>make -C ld install</userinput></screen>
 
-<para>Amend the GCC specs file:</para>
+<para>From this point onwards, everything will link only
+against the libraries in <filename class="directory">/tools/lib</filename>.</para>
+
+<note><para>If the earlier warning to retain the Binutils source and
+build directories from the first pass was missed, ignore the above
+command. This results in a small chance that the subsequent testing
+programs will link against libraries on the host. This is not ideal,
+but it is not a major problem. The situation is corrected when the
+second pass of Binutils is installed later.</para></note>
+
+<para>Now that the adjusted linker is installed, the Binutils build and source
+directories should be removed.</para>
+
+<para>The next task is to amend the GCC specs file so that it points
+to the new dynamic linker. A simple sed script will accomplish this:</para>
+
+<!-- Ampersands are needed to allow copy and paste -->
 
 <screen><userinput>SPECFILE=`gcc --print-file specs` &amp;&amp;
 sed 's@ /lib/ld-linux.so.2@ /tools/lib/ld-linux.so.2@g' \
@@ -20,24 +42,71 @@ sed 's@ /lib/ld-linux.so.2@ /tools/lib/ld-linux.so.2@g' \
 mv -f tempspecfile $SPECFILE &amp;&amp;
 unset SPECFILE</userinput></screen>
 
-<para>Make clean-up:</para>
+<para><phrase condition="html">It is recommended that the above
+command be copy-and-pasted in order to ensure accuracy.</phrase>
+Alternatively, the specs file can be edited by hand. This is done by
+replacing every occurrence of <quote>/lib/ld-linux.so.2</quote> with
+<quote>/tools/lib/ld-linux.so.2</quote></para>
+
+<para>Be sure to visually inspect the specs file in order to verify the
+intended changes have been made.</para>
+
+<important><para>If working on a platform where the name of the
+dynamic linker is something other than
+<filename class="libraryfile">ld-linux.so.2</filename>, replace
+<quote>ld-linux.so.2</quote> with the name of the platform's
+dynamic linker in the above commands. Refer back to <xref
+linkend="ch-tools-toolchaintechnotes" role=","/> if
+necessary.</para></important>
+
+<para>There is a possibility that some include files from the host
+system have found their way into GCC's private include dir. This can
+happen as a result of GCC's <quote>fixincludes</quote> process, which runs as part
+of the GCC build. This is explained in more detail later in this
+chapter. Run the following command to eliminate this
+possibility:</para>
 
 <screen><userinput>rm -f /tools/lib/gcc/*/*/include/{pthread.h,bits/sigthread.h}</userinput></screen>
 
-<para>Test the tools:</para>
+<caution><para>At this point, it is imperative to stop and ensure that
+the basic functions (compiling and linking) of the new toolchain are
+working as expected. To perform a sanity check, run the following
+commands:</para>
 
 <screen><userinput>echo 'main(){}' &gt; dummy.c
 cc dummy.c
 readelf -l a.out | grep ': /tools'</userinput></screen>
 
-<para>The output of the last command will be of the form:</para>
+<para>If everything is working correctly, there should be no errors,
+and the output of the last command will be of the form:</para>
 
 <screen><computeroutput>[Requesting program interpreter: 
     /tools/lib/ld-linux.so.2]</computeroutput></screen>
 
-<para>Remove the test files:</para>
+<para>Note that <filename class="directory">/tools/lib</filename>
+appears as the prefix of the dynamic linker.</para>
 
-<screen><userinput>rm dummy.c a.out</userinput></screen>
+<para>If the output is not shown as above or there was no output at
+all, then something is wrong. Investigate and retrace the steps to
+find out where the problem is and correct it. This issue must be
+resolved before continuing on. First, perform the sanity check again,
+using <command>gcc</command> instead of <command>cc</command>. If this
+works, then the <filename class="symlink">/tools/bin/cc</filename> symlink is missing.
+Revisit <xref linkend="ch-tools-gcc-pass1" role=","/> and install the symlink.
+Next, ensure that the <envar>PATH</envar> is correct. This can be checked by running
+<command>echo $PATH</command> and verifying that <filename
+class="directory">/tools/bin</filename> is at the head of the list. If
+the <envar>PATH</envar> is wrong it could mean that you are not logged in as user
+<emphasis>lfs</emphasis> or that something went wrong back in <xref
+linkend="ch-tools-settingenviron" role="."/> Another option is that something
+may have gone wrong with the specs file amendment above. In this case,
+redo the specs file amendment<phrase condition="html">, being careful to copy-and-paste the
+commands</phrase>.</para>
 
+<para>Once all is well, clean up the test files:</para>
+
+<screen><userinput>rm dummy.c a.out</userinput></screen>
+</caution>
 
 </sect1>
+
diff --git a/chapter05/bash.xml b/chapter05/bash.xml
index 62feb7904..930bd964a 100644
--- a/chapter05/bash.xml
+++ b/chapter05/bash.xml
@@ -7,8 +7,12 @@
 <title>Bash-&bash-version;</title>
 <?dbhtml filename="bash.html"?>
 
+<indexterm zone="ch-tools-bash">
+<primary sortas="a-Bash">Bash</primary>
+<secondary>tools</secondary></indexterm>
 
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bash.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -16,12 +20,16 @@
 <seglistitem><seg>1.2 SBU</seg><seg>27 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bash.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Bash</title>
 
-<para>Apply a patch:</para>
+<!-- Edit Me -->
+<para>Bash has a problem when compiled against newer versions of Glibc, causing
+it to hang inappropriately.  This patch fixes the problem:</para>
 
 <screen><userinput>patch -Np1 -i ../bash-&bash-version;-avoid_WCONTINUED-1.patch</userinput></screen>
 
@@ -29,21 +37,39 @@
 
 <screen><userinput>./configure --prefix=/tools --without-bash-malloc</userinput></screen>
 
-<para>Compile the program:</para>
+<para>The meaning of the configure option:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--without-bash-malloc</parameter></term>
+<listitem><para>This options turns off the use of Bash's memory
+allocation (malloc) function which is known to cause segmentation
+faults. By turning this option off, Bash will use the malloc functions
+from Glibc which are more stable.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make test</userinput>.</para>
+<para>To test the results, issue: <userinput>make
+tests</userinput>.</para>
 
-<para>Then install it :</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<para>Create a symlink:</para>
+<para>Make a link for the programs that use <command>sh</command> for
+a shell:</para>
 
 <screen><userinput>ln -s bash /tools/bin/sh</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref linkend="contents-bash" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/binutils-pass1.xml b/chapter05/binutils-pass1.xml
index 4dc8b3e1a..9f35ae722 100644
--- a/chapter05/binutils-pass1.xml
+++ b/chapter05/binutils-pass1.xml
@@ -7,7 +7,12 @@
 <title>Binutils-&binutils-version; - Pass 1</title>
 <?dbhtml filename="binutils-pass1.html"?>
 
+<indexterm zone="ch-tools-binutils-pass1">
+<primary sortas="a-Binutils">Binutils</primary>
+<secondary>tools, pass 1</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,44 +20,134 @@
 <seglistitem><seg>1.0 SBU</seg><seg>194 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Binutils</title>
 
-<para>Create a build dir:</para>
+<para>It is important that Binutils be the first package compiled
+because both Glibc and GCC perform various tests on the available
+linker and assembler to determine which of their own features to
+enable.</para>
+
+<para>This package is known to have issues when its default
+optimization flags (including the <parameter>-march</parameter> and
+<parameter>-mcpu</parameter> options) are changed. If any environment
+variables that override default optimizations have been defined, such
+as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
+unset them when building Binutils.</para>
+
+<para>The Binutils documentation recommends building Binutils outside of the
+source directory in a dedicated build directory:</para>
 
 <screen><userinput>mkdir ../binutils-build
 cd ../binutils-build</userinput></screen>
 
-<note><para>If you want the SBU values you could wrap the four commands in a 
-<command>time</command> command like this: 
-<userinput>time { ./configure ... &amp;&amp; ... &amp;&amp; ...
-&amp;&amp; make install; }</userinput>.</para></note>
+<note><para>In order for the SBU values listed in the rest of the book
+to be of any use, measure the time it takes to build this package from
+the configuration, up to and including the first install. To achieve
+this easily, wrap the four commands in a <command>time</command>
+command like this: <userinput>time { ./configure ... &amp;&amp; ...
+&amp;&amp; ... &amp;&amp; make install; }</userinput>.</para></note>
 
 <para>Now prepare Binutils for compilation:</para>
 
 <screen><userinput>../binutils-&binutils-version;/configure --prefix=/tools \
     --disable-nls</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--prefix=/tools</parameter></term>
+<listitem><para>This tells the configure script to prepare to install the Binutils
+programs in the <filename class="directory">/tools</filename> directory.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--disable-nls</parameter></term>
+<listitem><para>This disables internationalization. This is not needed
+for the static programs, and NLS can cause problems when linking
+statically.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Continue with compiling the package:</para>
 
 <screen><userinput>make configure-host
 make LDFLAGS="-all-static"</userinput></screen>
 
-<para>Now install the package:</para>
+<para>The meaning of the make parameters:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>configure-host</parameter></term>
+<listitem><para>This forces all subdirectories to be configured
+immediately. A statically-linked build will fail without it. Use this
+option to work around the problem.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>LDFLAGS="-all-static"</parameter></term>
+<listitem><para>This tells the linker that all Binutils programs
+should be linked statically. However, strictly speaking,
+<parameter>"-all-static"</parameter> is passed to the
+<command>libtool</command> program, which then passes
+<parameter>"-static"</parameter> to the linker.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Compilation is now complete. Ordinarily we would now run the
+test suite, but at this early stage the test suite framework (Tcl,
+Expect, and DejaGNU) is not yet in place. The benefits of running the
+tests at this point are minimal since the programs from this
+first pass will soon be replaced by those from the second.</para>
+
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<para>Now prepare the linker for the <quote>Adjusting</quote> phase later on:</para>
+<para>Next, prepare the linker for the <quote>Adjusting</quote> phase
+later on:</para>
 
 <screen><userinput>make -C ld clean
 make -C ld LDFLAGS="-all-static" LIB_PATH=/tools/lib</userinput></screen>
 
-<warning><para><emphasis>Do not yet remove</emphasis> the Binutils build and
-source directories. You will need them again in their current state a bit
-further on in this chapter.</para></warning>
+<para>The meaning of the make parameters:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>-C ld clean</parameter></term>
+<listitem><para>This tells the make program to remove all compiled
+files in the <filename class="directory">ld</filename>
+subdirectory.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>-C ld LDFLAGS="-all-static"
+LIB_PATH=/tools/lib</parameter></term>
+<listitem><para>This option rebuilds everything in the
+<filename class="directory">ld</filename> subdirectory. Specifying 
+the <envar>LIB_PATH</envar> Makefile variable on the command 
+line allows us to override the default value
+and point it to the temporary tools location. The value of this variable
+specifies the linker's default library search path. This preparation
+is used later in the chapter.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<warning><para><emphasis>Do not</emphasis> remove the Binutils
+build and source directories yet. These will be needed again in their
+current state later in this chapter.</para></warning>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-binutils" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/binutils-pass2.xml b/chapter05/binutils-pass2.xml
index 0c28271f7..85a574309 100644
--- a/chapter05/binutils-pass2.xml
+++ b/chapter05/binutils-pass2.xml
@@ -7,7 +7,14 @@
 <title>Binutils-&binutils-version; - Pass 2</title>
 <?dbhtml filename="binutils-pass2.html"?>
 
+<indexterm zone="ch-tools-binutils-pass2">
+<primary sortas="a-Binutils">Binutils</primary>
+<secondary>tools, pass 2</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude"
+	href="../chapter06/binutils.xml"
+	xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,39 +22,57 @@
 <seglistitem><seg>1.5 SBU</seg><seg>108 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude"
+	href="../chapter06/binutils.xml"
+	xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Re-installation of Binutils</title>
 
+<para>This package is known to have issues when its default
+optimization flags (including the <parameter>-march</parameter> and
+<parameter>-mcpu</parameter> options) are changed. If any environment
+variables that override default optimizations have been defined, such
+as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
+unset them when building Binutils.</para>
+
 <para>Create a separate build directory again:</para>
 
 <screen><userinput>mkdir ../binutils-build
 cd ../binutils-build</userinput></screen>
 
-<para>Now prepare Binutils for compilation:</para>
+<para>Prepare Binutils for compilation:</para>
 
 <screen><userinput>../binutils-&binutils-version;/configure --prefix=/tools \
     --enable-shared --with-lib-path=/tools/lib</userinput></screen>
 
-<para>Compile the package:</para>
+<para>The meaning of the new configure option:</para>
 
-<screen><userinput>make</userinput></screen>
+<variablelist>
+<varlistentry>
+<term><parameter>--with-lib-path=/tools/lib</parameter></term>
+<listitem><para>This tells the configure script to specify the library
+search path during the compilation of Binutils, resulting in <filename
+class="directory">/tools/lib</filename> being passed to the linker.
+This prevents the linker from searching through library directories on
+the host.</para></listitem>
+</varlistentry>
+</variablelist>
 
-<para>Test the results:</para>
+<para>Compile the package:</para>
 
-<!-- NEW -->
-<screen><userinput>make -k check</userinput></screen>
+<screen><userinput>make</userinput></screen>
 
-<para>Except for a few known failures, the binutils tests should all pass. The
-exceptions to this rule are as follows:</para>
+<para>Compilation is now complete. As discussed earlier, running the
+test suite is not mandatory for the temporary tools here in this
+chapter. To run the Binutils test suite anyway, issue the following
+command:</para>
 
-<screen><computeroutput>* 5 FAIL (unexpected failure) for visibility
-* 1 FAIL for selective4
-* 1 FAIL for selective5</computeroutput></screen>
-<!-- END NEW-->
+<screen><userinput>make check</userinput></screen>
 
-<para>And install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
@@ -58,10 +83,16 @@ chapter:</para>
 make -C ld LIB_PATH=/usr/lib:/lib</userinput></screen>
 
 
-<warning><para><emphasis>Do not yet remove</emphasis> the Binutils source and
-build directories. You will need these directories again in the next chapter
-in the state they are in now.</para></warning>
+<warning><para><emphasis>Do not</emphasis> remove the Binutils source and
+build directories yet. These directories will be needed again in the next
+chapter in their current state.</para></warning>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-binutils" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/bison.xml b/chapter05/bison.xml
index e3572e99d..dc237997d 100644
--- a/chapter05/bison.xml
+++ b/chapter05/bison.xml
@@ -7,7 +7,12 @@
 <title>Bison-&bison-version;</title>
 <?dbhtml filename="bison.html"?>
 
+<indexterm zone="ch-tools-bison">
+<primary sortas="a-Bison">Bison</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bison.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.6 SBU</seg><seg>10.6 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bison.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,13 +35,19 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make check</userinput>.</para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
-<para>Now install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-bison" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/bzip2.xml b/chapter05/bzip2.xml
index fb2ae264e..a45dee979 100644
--- a/chapter05/bzip2.xml
+++ b/chapter05/bzip2.xml
@@ -7,7 +7,12 @@
 <title>Bzip2-&bzip2-version;</title>
 <?dbhtml filename="bzip2.html"?>
 
+<indexterm zone="ch-tools-bzip2">
+<primary sortas="a-Bzip2">Bzip2</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bzip2.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,20 +20,28 @@
 <seglistitem><seg>0.1 SBU</seg><seg>2.5 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bzip2.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Bzip2</title>
 
-<para>The Bzip2 package doesn't contain a <command>configure</command>
-script. Compile it with a straightforward:</para>
+<para>The Bzip2 package does not contain a <command>configure</command>
+script. Compile it with:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>And install it:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make PREFIX=/tools install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-bzip2" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/chapter05.xml b/chapter05/chapter05.xml
index 353071c9d..9c567c530 100644
--- a/chapter05/chapter05.xml
+++ b/chapter05/chapter05.xml
@@ -14,9 +14,6 @@
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="binutils-pass1.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="gcc-pass1.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="linux-libc-headers.xml"/>
-<!--
-<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="kernel-headers.xml"/>
--->
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="glibc.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="adjusting.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="tcl.xml"/>
@@ -44,9 +41,6 @@
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="flex.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="util-linux.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="perl.xml"/>
-<!--
-<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="udev.xml"/>
--->
 <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="stripping.xml"/>
 
 </chapter>
diff --git a/chapter05/coreutils.xml b/chapter05/coreutils.xml
index f99768465..e7bf67d37 100644
--- a/chapter05/coreutils.xml
+++ b/chapter05/coreutils.xml
@@ -7,7 +7,12 @@
 <title>Coreutils-&coreutils-version;</title>
 <?dbhtml filename="coreutils.html"?>
 
+<indexterm zone="ch-tools-coreutils">
+<primary sortas="a-Coreutils">Coreutils</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/coreutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.9 SBU</seg><seg>69 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/coreutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -24,17 +31,44 @@
 
 <screen><userinput>DEFAULT_POSIX2_VERSION=199209 ./configure --prefix=/tools</userinput></screen>
 
+<para>This package has an issue when compiled against versions of
+Glibc later than 2.3.2. Some of the Coreutils utilities (such as
+<command>head</command>, <command>tail</command>, and
+<command>sort</command>) will reject their traditional syntax, a
+syntax that has been in use for approximately 30 years. This old
+syntax is so pervasive that compatibility should be preserved until
+the many places where it is used can be updated. Backwards
+compatibility is achieved by setting the
+<envar>DEFAULT_POSIX2_VERSION</envar> environment variable to
+<quote>199209</quote> in the above command. If you do not want
+Coreutils to be backwards compatible with the traditional syntax, then
+omit setting the <envar>DEFAULT_POSIX2_VERSION</envar>
+environment variable. It is important to remember that doing so will
+have consequences, including the need to patch the many packages that
+still use the old syntax. Therefore, it is recommended that the
+instructions be followed exactly as given above.</para>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the result, issue:
-<userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput></para>
+<para>To test the results, issue: <userinput>make
+RUN_EXPENSIVE_TESTS=yes check</userinput>.  The
+<parameter>RUN_EXPENSIVE_TESTS=yes</parameter> parameter tells the
+test suite to run several additional tests that are considered
+relatively expensive (in terms of CPU power and memory usage) on some
+platforms, but generally are not a problem on Linux.</para>
 
-<para>And install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-coreutils" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/dejagnu.xml b/chapter05/dejagnu.xml
index 25e3e87b2..2b9703030 100644
--- a/chapter05/dejagnu.xml
+++ b/chapter05/dejagnu.xml
@@ -3,13 +3,14 @@
   <!ENTITY % general-entities SYSTEM "../general.ent">
   %general-entities;
 ]>
-<sect1 id="ch-tools-dejagnu" xreflabel="DejaGNU" role="wrap">
+<sect1 id="ch-tools-dejagnu" role="wrap">
 <title>DejaGNU-&dejagnu-version;</title>
 <?dbhtml filename="dejagnu.html"?>
 
 <indexterm zone="ch-tools-dejagnu"><primary sortas="a-DejaGNU">DejaGNU</primary></indexterm>
 
 <sect2 role="package"><title/>
+<para>The DejaGNU package contains a framework for testing other programs.</para>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -17,6 +18,11 @@
 <seglistitem><seg>0.1 SBU</seg><seg>8.6 MB</seg></seglistitem>
 </segmentedlist>
 
+<segmentedlist>
+<segtitle>DejaGNU installation depends on</segtitle>
+<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils,
+GCC, Glibc, Grep, Make, and Sed</seg></seglistitem>
+</segmentedlist>
 </sect2>
 
 <sect2 role="installation">
@@ -32,11 +38,28 @@
 
 </sect2>
 
+
 <sect2 id="contents-dejagnu" role="content"><title>Contents of DejaGNU</title>
 
-<para>See testing</para>
+<segmentedlist>
+<segtitle>Installed program</segtitle>
+<seglistitem><seg>runtest</seg></seglistitem>
+</segmentedlist>
 
-</sect2>
+<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead>
+<?dbfo list-presentation="list"?>
+
+<varlistentry id="runtest">
+<term><command>runtest</command></term>
+<listitem>
+<para>A wrapper script that locates the proper
+<command>expect</command> shell and then runs DejaGNU</para>
+<indexterm zone="ch-tools-dejagnu runtest"><primary sortas="b-runtest">runtest</primary></indexterm>
+</listitem>
+</varlistentry>
+</variablelist>
 
+</sect2>
 
 </sect1>
+
diff --git a/chapter05/diffutils.xml b/chapter05/diffutils.xml
index 7d9d49eb5..b3408d512 100644
--- a/chapter05/diffutils.xml
+++ b/chapter05/diffutils.xml
@@ -7,7 +7,12 @@
 <title>Diffutils-&diffutils-version;</title>
 <?dbhtml filename="diffutils.html"?>
 
+<indexterm zone="ch-tools-diffutils">
+<primary sortas="a-Diffutils">Diffutils</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/diffutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.1 SBU</seg><seg>7.5 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/diffutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,10 +35,18 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>And install it:</para>
+<para>This package does not come with a test suite.</para>
+
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-diffutils" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/expect.xml b/chapter05/expect.xml
index 11887dfd2..5d99eaf4d 100644
--- a/chapter05/expect.xml
+++ b/chapter05/expect.xml
@@ -3,13 +3,15 @@
   <!ENTITY % general-entities SYSTEM "../general.ent">
   %general-entities;
 ]>
-<sect1 id="ch-tools-expect" xreflabel="Expect" role="wrap">
+<sect1 id="ch-tools-expect" role="wrap">
 <title>Expect-&expect-version;</title>
 <?dbhtml filename="expect.html"?>
 
 <indexterm zone="ch-tools-expect"><primary sortas="a-Expect">Expect</primary></indexterm>
 
 <sect2 role="package"><title/>
+<para>The Expect package contains a program for carrying out scripted dialogues
+with other interactive programs.</para>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -17,12 +19,18 @@
 <seglistitem><seg>0.1 SBU</seg><seg>3.9 MB</seg></seglistitem>
 </segmentedlist>
 
+<segmentedlist>
+<segtitle>Expect installation depends on</segtitle>
+<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils,
+GCC, Glibc, Grep, Make, Sed, and Tcl</seg></seglistitem>
+</segmentedlist>
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Expect</title>
 
-<para>Apply a patch:</para>
+<para>First, fix a bug that can result in false failures during the GCC test
+suite run:</para>
 
 <screen><userinput>patch -Np1 -i ../expect-&expect-version;-spawn-1.patch</userinput></screen>
 
@@ -30,26 +38,84 @@
 
 <screen><userinput>./configure --prefix=/tools --with-tcl=/tools/lib --with-x=no</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--with-tcl=/tools/lib</parameter></term>
+<listitem><para>This ensures that the configure script finds the Tcl installation in
+the temporary tools location instead of possibly locating an existing
+one on the host system.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--with-x=no</parameter></term>
+<listitem><para>This tells the configure script not to search for Tk
+(the Tcl GUI component) or the X Window System libraries, both of
+which may reside on the host system.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Build the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make test</userinput></para>
+<para>To test the results, issue: <userinput>make test</userinput>.
+Note that the Expect test suite is known to experience failures under
+certain host conditions that are not within our control. Therefore,
+test suite failures here are not surprising and are not considered
+critical.</para>
 
-<para>And install it:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make SCRIPTS="" install</userinput></screen>
 
-<para>You can now remove the source directories of both Tcl and Expect.</para>
+<para>The meaning of the make parameter:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>SCRIPTS=""</parameter></term>
+<listitem><para>This prevents installation of the supplementary expect
+scripts, which are not needed.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>The source directories of both Tcl and Expect can now be removed.</para>
 
 </sect2>
 
 <sect2 id="contents-expect" role="content"><title>Contents of Expect</title>
 
-<para>See testing</para>
+<segmentedlist>
+<segtitle>Installed program</segtitle>
+<segtitle>Installed library</segtitle>
+<seglistitem><seg>expect</seg><seg>libexpect-5.42.a</seg></seglistitem>
+</segmentedlist>
+
+<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead>
+<?dbfo list-presentation="list"?>
+
+<varlistentry id="expect">
+<term><command>expect</command></term>
+<listitem>
+<para>Communicates with other interactive
+programs according to a script</para>
+<indexterm zone="ch-tools-expect expect"><primary sortas="b-expect">expect</primary></indexterm>
+</listitem>
+</varlistentry>
+
+<varlistentry id="libexpect">
+<term><filename class="libraryfile">libexpect-5.42.a</filename></term>
+<listitem>
+<para>Contains functions that allow Expect to be used as a Tcl extension or to
+be used directly from C or C++ (without Tcl)</para>
+<indexterm zone="ch-tools-expect libexpect"><primary
+sortas="c-libexpect-5.42">libexpect-5.42</primary></indexterm>
+</listitem>
+</varlistentry>
+</variablelist>
 
 </sect2>
 
-
 </sect1>
+
diff --git a/chapter05/findutils.xml b/chapter05/findutils.xml
index 0da1b5bc0..d75f15b90 100644
--- a/chapter05/findutils.xml
+++ b/chapter05/findutils.xml
@@ -7,7 +7,12 @@
 <title>Findutils-&findutils-version;</title>
 <?dbhtml filename="findutils.html"?>
 
+<indexterm zone="ch-tools-findutils">
+<primary sortas="a-Findutils">Findutils</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/findutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>7.6 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/findutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,13 +35,19 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
-<para>And install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-findutils" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/flex.xml b/chapter05/flex.xml
index d8f01a11e..c78a52ffc 100644
--- a/chapter05/flex.xml
+++ b/chapter05/flex.xml
@@ -3,11 +3,16 @@
   <!ENTITY % general-entities SYSTEM "../general.ent">
   %general-entities;
 ]>
-<sect1 id="ch-tools-flex" xreflabel="Flex" role="wrap">
+<sect1 id="ch-tools-flex" role="wrap">
 <title>Flex-&flex-version;</title>
 <?dbhtml filename="flex.html"?>
 
+<indexterm zone="ch-tools-flex">
+<primary sortas="a-Flex">Flex</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/flex.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,16 +20,22 @@
 <seglistitem><seg>0.6 SBU</seg><seg>10.6 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/flex.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Flex</title>
 
-<para>Apply a patch:</para>
+<para>Flex contains several known bugs. These can be fixed with the
+following patch:</para>
 
 <screen><userinput>patch -Np1 -i ../flex-&flex-version;-debian_fixes-2.patch</userinput></screen>
 
-<para>Touch the man-page:</para>
+<para>The GNU autotools will detect that the Flex source code has been
+modified by the previous patch and tries to update the manual page
+accordingly.  This does not work on many systems, and the default page is
+fine, so make sure it does not get regenerated:</para>
 
 <screen><userinput>touch doc/flex.1</userinput></screen>
 
@@ -39,10 +50,16 @@
 <para>To test the results, issue:
 <userinput>make check</userinput>.</para>
 
-<para>Now install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-flex" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/gawk.xml b/chapter05/gawk.xml
index 62ad8768d..e72817f81 100644
--- a/chapter05/gawk.xml
+++ b/chapter05/gawk.xml
@@ -7,7 +7,12 @@
 <title>Gawk-&gawk-version;</title>
 <?dbhtml filename="gawk.html"?>
 
+<indexterm zone="ch-tools-gawk">
+<primary sortas="a-Gawk">Gawk</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gawk.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>17 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gawk.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,13 +35,19 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make check</userinput></para>
+<para>To test the results (not necessary), issue: <userinput>make
+check</userinput>.</para>
 
-<para>And install it:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-gawk" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/gcc-pass1.xml b/chapter05/gcc-pass1.xml
index 39b343a2e..503438558 100644
--- a/chapter05/gcc-pass1.xml
+++ b/chapter05/gcc-pass1.xml
@@ -7,7 +7,12 @@
 <title>GCC-&gcc-version; - Pass 1</title>
 <?dbhtml filename="gcc-pass1.html"?>
 
+<indexterm zone="ch-tools-gcc-pass1">
+<primary sortas="a-GCC">GCC</primary>
+<secondary>tools, pass 1</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,36 +20,117 @@
 <seglistitem><seg>4.4 SBU</seg><seg>300 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of GCC</title>
 
-<para>Create a build dir:</para>
+<para>Unpack only the gcc-core tarball because neither the C++
+compiler nor the test suite will be needed here.</para>
+
+<para>This package is known to have issues when its default
+optimization flags (including the <parameter>-march</parameter> and
+<parameter>-mcpu</parameter> options) are changed. If any environment
+variables that override default optimizations have been defined, such
+as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
+unset them when building GCC.</para>
+
+<para>The GCC documentation recommends building GCC outside of the
+source directory in a dedicated build directory:</para>
 
 <screen><userinput>mkdir ../gcc-build
 cd ../gcc-build</userinput></screen>
 
 <para>Prepare GCC for compilation:</para>
 
-<!--NEW-->
-<screen><userinput>CC="gcc -B/usr/bin" ../gcc-&gcc-version;/configure \
-    --prefix=/tools --libexecdir=/tools/lib \
-    --with-local-prefix=/tools --disable-nls \
-    --enable-shared --enable-languages=c</userinput></screen>
+<screen><userinput>../gcc-&gcc-version;/configure --prefix=/tools \
+    --libexecdir=/tools/lib --with-local-prefix=/tools \
+    --disable-nls --enable-shared --enable-languages=c</userinput></screen>
+
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--with-local-prefix=/tools</parameter></term>
+<listitem><para>The purpose of this switch is to remove <filename class="directory">/usr/local/include</filename>
+from <command>gcc</command>'s include search path. This is not absolutely
+essential, however, it helps to minimize the influence of the host
+system.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-shared</parameter></term>
+<listitem><para>This switch may seem counter-intuitive at first.
+However, this switch allows the building of
+<filename class="libraryfile">libgcc_s.so.1</filename> and
+<filename class="libraryfile">libgcc_eh.a</filename>, and having
+<filename class="libraryfile">libgcc_eh.a</filename> available ensures that the configure
+script for Glibc (the next package we compile) produces the proper
+results. Note that the GCC binaries will still be linked statically
+because this is controlled by the <parameter>-static</parameter> value of
+the <envar>BOOT_LDFLAGS</envar> variable in the next
+step.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-languages=c</parameter></term>
+<listitem><para>This option ensures that only the C compiler is built.
+This option is only needed when you have downloaded and unpacked the
+full GCC tarball, as opposed to just the gcc-core
+tarball.</para></listitem>
+</varlistentry>
+</variablelist>
 
 <para>Continue with compiling the package:</para>
 
 <screen><userinput>make BOOT_LDFLAGS="-static" bootstrap</userinput></screen>
 
-<para>Now install the package:</para>
+<para>The meaning of the make parameters:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>BOOT_LDFLAGS="-static"</parameter></term>
+<listitem><para>This tells GCC to link its programs statically.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>bootstrap</parameter></term>
+<listitem><para>This target does not just compile GCC, but compiles it
+several times. It uses the programs compiled in a first round to
+compile itself a second time, and then again a third time. It then
+compares these second and third compiles to make sure it can reproduce
+itself flawlessly.  This also implies that it was compiled
+correctly.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Compilation is now complete. At this point, the test suite would
+normally be run, but, as mentioned before, the test suite framework is
+not in place yet. The benefits of running the tests at this point
+are minimal since the programs from this first pass will soon be
+replaced.</para>
+
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<para>Create a symlink:</para>
+<para>As a finishing touch, create a symlink. Many programs and
+scripts run <command>cc</command> instead of <command>gcc</command>, which is used to keep programs generic
+and therefore usable on all kinds of UNIX systems where the GNU C compiler
+is not always installed. Running <command>cc</command> leaves the system administrator
+free to decide which C compiler to install.</para>
 
 <screen><userinput>ln -s gcc /tools/bin/cc</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-gcc" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/gcc-pass2.xml b/chapter05/gcc-pass2.xml
index 9058c02ea..202f9a0d9 100644
--- a/chapter05/gcc-pass2.xml
+++ b/chapter05/gcc-pass2.xml
@@ -7,6 +7,10 @@
 <title>GCC-&gcc-version; - Pass 2</title>
 <?dbhtml filename="gcc-pass2.html"?>
 
+<indexterm zone="ch-tools-gcc-pass2">
+<primary sortas="a-GCC">GCC</primary>
+<secondary>tools, pass 2</secondary></indexterm>
+
 <sect2 role="package"><title/>
 
 <segmentedlist>
@@ -15,25 +19,88 @@
 <seglistitem><seg>11.0 SBU</seg><seg>274 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Re-installation of GCC</title>
 
-<para>Check if there is PTYs for the test suites:</para>
+<para>This package is known to have issues when its default
+optimization flags (including the <parameter>-march</parameter> and
+<parameter>-mcpu</parameter> options) are changed. If any environment
+variables that override default optimizations have been defined, such
+as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
+unset them when building GCC.</para>
+
+<para>The tools required to test GCC and Binutils&mdash;Tcl, Expect
+and DejaGNU&mdash;are installed now. GCC and Binutils can now be
+rebuilt, linking them against the new Glibc and testing them properly
+(if running the test suites in this chapter). Please note that these
+test suites are highly dependent on properly functioning PTYs which
+are provided by the host. PTYs are most commonly implemented via the
+<systemitem class="filesystem">devpts</systemitem> file system. Check
+to see if the host system is set up correctly in this regard by
+performing a quick test:</para>
 
 <screen><userinput>expect -c "spawn ls"</userinput></screen>
 
-<para>Apply two patches:</para>
+<para>The response might be:</para>
+
+<screen><computeroutput>The system has no more ptys.  
+Ask your system administrator to create more.</computeroutput></screen>
+
+<para>If the above message is received, the host does not have its
+PTYs set up properly. In this case, there is no point in running the
+test suites for GCC and Binutils until this issue is resolved. Please
+consult the LFS Wiki at <ulink url="&wiki-root;"/> for more
+information on how to get PTYs working.</para>
+
+<para>Because the C and the C++ compilers will be built, unpack both
+the core and the g++ tarballs (as well as test suite, if you want to
+run the tests). By unpacking them in the working directory, they will
+all unfold into a single <filename
+class="directory">gcc-&gcc-version;/</filename> subdirectory.</para>
+
+<para>First correct a known problem and make an essential adjustment:</para>
 
 <screen><userinput>patch -Np1 -i ../gcc-&gcc-version;-no_fixincludes-1.patch
 patch -Np1 -i ../gcc-&gcc-version;-specs-2.patch</userinput></screen>
 
+<para>The first patch disables the GCC <command>fixincludes</command>
+script. This was briefly mentioned earlier, but a more in-depth
+explanation of the fixincludes process is warranted here. Under normal
+circumstances, the GCC <command>fixincludes</command> script scans the
+system for header files that need to be fixed. It might find that some
+Glibc header files on the host system need to be fixed, and will fix
+them and put them in the GCC private include directory. In <xref
+linkend="chapter-building-system"/>, after the newer Glibc has been
+installed, this private include directory will be searched before the
+system include directory.  This may result in GCC finding the fixed
+headers from the host system, which most likely will not match the
+Glibc version used for the LFS system.</para>
+
+<para>The second patch changes GCC's default location of the dynamic
+linker (typically <filename class="libraryfile">ld-linux.so.2</filename>). It also removes
+<filename class="directory">/usr/include</filename> from GCC's include
+search path. Patching now rather than adjusting the specs file after
+installation ensures that the new dynamic linker is used during the
+actual build of GCC. That is, all of the final (and temporary)
+binaries created during the build will link against the new
+Glibc.</para>
+
+<important><para>The above patches are critical in ensuring a
+successful overall build. Do not forget to apply
+them.</para></important>
+
 <para>Create a separate build directory again:</para>
 
 <screen><userinput>mkdir ../gcc-build
 cd ../gcc-build</userinput></screen>
 
+<para>Before starting to build GCC, remember to unset any environment
+variables that override the default optimization flags.</para>
+
 <para>Now prepare GCC for compilation:</para>
 
 <screen><userinput>../gcc-&gcc-version;/configure --prefix=/tools \
@@ -42,36 +109,105 @@ cd ../gcc-build</userinput></screen>
     --enable-threads=posix --enable-__cxa_atexit \
     --enable-languages=c,c++ --disable-libstdcxx-pch</userinput></screen>
 
+<para>The meaning of the new configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--enable-clocale=gnu</parameter></term>
+<listitem><para>This option ensures the correct locale model is
+selected for the C++ libraries under all circumstances. If the
+configure script finds the <emphasis>de_DE</emphasis> locale installed, it will select the
+correct gnu locale model. However, if the <emphasis>de_DE</emphasis> locale is not
+installed, there is the risk of building Application Binary Interface
+(ABI)-incompatible C++ libraries because the incorrect generic locale
+model may be selected.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-threads=posix</parameter></term>
+<listitem><para>This enables C++ exception handling for multi-threaded
+code.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-__cxa_atexit</parameter></term>
+<listitem><para>This option allows use of
+<emphasis>__cxa_atexit</emphasis>, rather than
+<emphasis>atexit</emphasis>, to register C++ destructors for local
+statics and global objects.  This option is essential for fully
+standards-compliant handling of destructors. It also effects the C++
+ABI, and therefore results in C++ shared libraries and C++ programs
+that are interoperable with other Linux
+distributions.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-languages=c,c++</parameter></term>
+<listitem><para>This option
+ensures that both the C and C++ compilers are built.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--disable-libstdcxx-pch</parameter></term>
+<listitem><para>Do not build the pre-compiled header (PCH) for
+<filename class="libraryfile">libstdc++</filename>. It takes up a lot of space,
+and we have no use for it.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>Test the results</para>
+<para>There is no need to use the <parameter>bootstrap</parameter>
+target now because the compiler being used to compile this GCC was
+built from the exact same version of the GCC sources used
+earlier.</para>
+
+<para>Compilation is now complete. As previously mentioned, running
+the test suites for the temporary tools compiled in this chapter is
+not mandatory. To run the GCC test suite anyway, use the following
+command:</para>
 
 <screen><userinput>make -k check</userinput></screen>
 
-<para>To get a summary of the test suite results, run this:</para>
+<para>The <parameter>-k</parameter> flag is used to make the test suite run
+through to completion and not stop at the first failure. The GCC test
+suite is very comprehensive and is almost guaranteed to generate a few
+failures. To receive a summary of the test suite results, run:</para>
  
 <screen><userinput>../gcc-&gcc-version;/contrib/test_summary</userinput></screen>
 
 <para>For only the summaries, pipe the output through
-<userinput>grep -A7 Summ</userinput></para>
+<userinput>grep -A7 Summ</userinput>.</para>
 
 <para>Results can be compared to those posted to the gcc-testresults
-mailing list to see similar configurations to the one being built. For an example of how
-current GCC-&gcc-version; should look on i686-pc-linux-gnu, see
-<ulink url="http://gcc.gnu.org/ml/gcc-testresults/2004-11/msg00569.html"/>.</para>
+mailing list to see similar configurations to the one being built. For
+an example of how current GCC-&gcc-version; should look on
+i686-pc-linux-gnu, see <ulink
+url="http://gcc.gnu.org/ml/gcc-testresults/2004-07/msg00179.html"/>.</para>
+
+<para>A few unexpected failures cannot always be avoided. The
+GCC developers are usually aware of these issues, but have not
+resolved them yet. Unless the test results are vastly different from
+those at the above URL, it is safe to continue.</para>
 
-<para>And finally install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<note><para>At this point it is strongly recommended to repeat the sanity check
-we performed earlier in this chapter. Refer back to
-<xref linkend="ch-tools-adjusting"/> and repeat the little test compilation. If
-the result is wrong, then most likely you forgot to apply the above mentioned
-GCC Specs patch.</para></note>
+<note><para>At this point it is strongly recommended to repeat the
+sanity check we performed earlier in this chapter. Refer back to <xref
+linkend="ch-tools-adjusting" role=","/> and repeat the test compilation.  If
+the result is wrong, the most likely reason is that the GCC Specs
+patch was not properly applied.</para></note>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-gcc" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/gettext.xml b/chapter05/gettext.xml
index feb4c38ed..ceca963c1 100644
--- a/chapter05/gettext.xml
+++ b/chapter05/gettext.xml
@@ -7,7 +7,12 @@
 <title>Gettext-&gettext-version;</title>
 <?dbhtml filename="gettext.html"?>
 
+<indexterm zone="ch-tools-gettext">
+<primary sortas="a-Gettext">Gettext</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gettext.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.5 SBU</seg><seg>55 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gettext.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -25,17 +32,46 @@
 <screen><userinput>./configure --prefix=/tools --disable-libasprintf \
     --disable-csharp</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--disable-libasprintf</parameter></term>
+<listitem><para>This flag tells Gettext not to build the
+<filename class="libraryfile">asprintf</filename> library. Because nothing in this 
+chapter or the next requires this library and Gettext gets rebuilt later,
+exclude it to save time and space.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--disable-csharp</parameter></term>
+<listitem><para>This tells Gettext not to use a C# compiler, even if a
+C# compiler is installed on the host. This needs to be done because
+once we enter the chroot environment, C# will no longer be
+available.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue: 
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make check</userinput>.
+This takes quite some time, around 7 SBUs. The Gettext test suite is
+known to experience failures under certain host conditions, for
+example when it finds a Java compiler on the host.  An experimental
+patch to disable Java is available from the LFS Patches project at
+<ulink url="&lfs-root;patches/"/>.</para>
 
-<para>And install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref linkend="contents-gettext" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/glibc.xml b/chapter05/glibc.xml
index dcb468a56..1e3d4925b 100644
--- a/chapter05/glibc.xml
+++ b/chapter05/glibc.xml
@@ -7,7 +7,12 @@
 <title>Glibc-&glibc-version;</title>
 <?dbhtml filename="glibc.html"?>
 
+<indexterm zone="ch-tools-glibc">
+<primary sortas="a-Glibc">Glibc</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/glibc.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,12 +20,26 @@
 <seglistitem><seg>11.8 SBU</seg><seg>800 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/glibc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Glibc</title>
 
-<para>Create a build dir:</para>
+<para>This package is known to have issues when its default
+optimization flags (including the <parameter>-march</parameter> and
+<parameter>-mcpu</parameter> options) are changed. If any environment
+variables that override default optimizations have been defined, such
+as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
+unset them when building Glibc.</para>
+
+<para>It should be noted that compiling Glibc in any way other than
+the method suggested in this book puts the stability of the system at
+risk.</para>
+
+<para>The Glibc documentation recommends building Glibc outside of the source
+directory in a dedicated build directory:</para>
 
 <screen><userinput>mkdir ../glibc-build
 cd ../glibc-build</userinput></screen>
@@ -33,32 +52,153 @@ cd ../glibc-build</userinput></screen>
     --without-gd --without-cvs --with-headers=/tools/include \
     --disable-selinux</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--disable-profile</parameter></term>
+<listitem><para>This builds the libraries without profiling
+information. Omit this option if profiling on the temporary tools is
+necessary.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-add-ons</parameter></term>
+<listitem><para>This tells Glibc to use the NPTL add-on as its threading 
+library.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-kernel=2.6.0</parameter></term>
+<listitem><para>This tells Glibc to compile the library with support
+for 2.6.x Linux kernels.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--with-binutils=/tools/bin</parameter></term>
+<listitem><para>While not required, this switch ensures that there are
+no errors pertaining to which Binutils programs get used during the
+Glibc build.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--without-gd</parameter></term>
+<listitem><para>This prevents the build of the
+<command>memusagestat</command> program, which insists on linking
+against the host's libraries (libgd, libpng, libz,
+etc.).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--without-cvs</parameter></term>
+<listitem><para>This prevents the Makefile files from
+attempting automatic CVS checkouts when using a CVS snapshot. While
+this command is not required, it is recommended because it suppresses
+an annoying, but harmless, warning about a missing autoconf
+program.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--with-headers=/tools/include</parameter></term>
+<listitem><para>This tells Glibc to compile itself against the headers recently
+installed to the tools directory, so that it knows exactly what features the
+kernel has and can optimize itself accordingly.</para></listitem>
+</varlistentry>
+
+<!-- Edit Me -->
+<varlistentry>
+<term><parameter>--disable-selinux</parameter></term>
+<listitem><para>When building from hosts using SELinux functionality
+(i.e. Fedora Core 3), glibc will try to integrate this functionality into
+itself, but will fail, because we do not have this functionality in the LFS
+tools enviornment.  This option will disable this, allowing glibc to build
+correctly, but will not otherwise affect the build.</para></listitem>
+</varlistentry>
+<!-- -->
+</variablelist>
+
+<para>During this stage the following warning might appear:</para>
+
+<blockquote><screen><computeroutput>configure: WARNING:
+*** These auxiliary programs are missing or 
+*** incompatible versions: msgfmt
+*** some features will be disabled.
+*** Check the INSTALL file for required versions.</computeroutput></screen></blockquote>
+
+<para>The missing or incompatible <command>msgfmt</command> program is
+generally harmless, but it can sometimes cause issues when running the
+test suite. This <command>msgfmt</command> program is part of the
+Gettext package which the host distribution should provide. If
+<command>msgfmt</command> is present but deemed incompatible, upgrade
+the host system's Gettext package or continue without it and see if
+the test suite runs without problems regardless.</para>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>Test the results:</para>
+<para>Compilation is now complete. As mentioned earlier, running the
+test suites for the temporary tools installed in this chapter is not
+mandatory. To run the Glibc test suite (if desired), the following
+command will do so:</para>
 
 <screen><userinput>make check</userinput></screen>
 
 <para>For a discussion of test failures that are of particular
-importance, please see <xref linkend="ch-system-glibc"/>.</para>
+importance, please see <xref linkend="ch-system-glibc" role="."/></para>
+
+<para>In this chapter, some tests can be adversely effected by
+existing tools or environmental issues on the host system. Glibc test
+suite failures in this chapter are typically not worrisome. The Glibc
+installed in <xref linkend="chapter-building-system"/> is the one that
+will ultimately end up being used, so that is the one that needs to pass
+most tests (even in <xref linkend="chapter-building-system"/>, some
+failures could still occur, for example, with the math tests).</para>
+
+<para>When experiencing a failure, make a note of it, then continue by
+reissuing the <command>make check</command> command. The test suite should pick up where it left
+off and continue. This stop-start sequence can be circumvented by
+issuing a <command>make -k check</command> command. If using this option, be sure to log the
+output so that the log file can be examined for failures later.</para>
+
+<para>The install stage of Glibc will issue a harmless warning at the
+end about the absence of <filename>/tools/etc/ld.so.conf</filename>. 
+Prevent this warning with:</para>
 
 <screen><userinput>mkdir /tools/etc
 touch /tools/etc/ld.so.conf</userinput></screen>
 
-<para>Now install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<para>To install the Glibc locales, use the following
+<para>Different countries and cultures have varying conventions for
+how to communicate. These conventions range from the format for
+representing dates and times to more complex issues, such as the
+language spoken. The <quote>internationalization</quote> of GNU
+programs works by locale.</para>
+
+<note><para>If the test suites are not being run in this chapter (as
+per the recommendation), there is no need to install the locales now.
+The appropriate locales will be installed in the next
+chapter.</para></note>
+
+<para>To install the Glibc locales anyway, use the following
 command:</para>
 
 <screen><userinput>make localedata/install-locales</userinput></screen>
 
-<para>An alternative to running the previous command is to install only those
-locales which you need or want. The following instructions, instead of the 
-install-locales target above, will install the minimum set of locales necessary 
+<para>To save time, an alternative to running the
+previous command (which generates and installs every locale Glibc is
+aware of) is to install only those locales that are wanted and needed.
+This can be achieved by using the <command>localedef</command>
+command. Information on this command is located in the
+<filename>INSTALL</filename> file in the Glibc source.  However, there
+are a number of locales that are essential in order for the tests of
+future packages to pass, in particular, the
+<emphasis>libstdc++</emphasis> tests from GCC. The following
+instructions, instead of the <parameter>install-locales</parameter>
+target used above, will install the minimum set of locales necessary
 for the tests to run successfully:</para>
 
 <screen><userinput>mkdir -p /tools/lib/locale
@@ -76,4 +216,10 @@ localedef -i ja_JP -f EUC-JP ja_JP</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-glibc" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/grep.xml b/chapter05/grep.xml
index 7af37c4b6..6cc9ce553 100644
--- a/chapter05/grep.xml
+++ b/chapter05/grep.xml
@@ -7,7 +7,12 @@
 <title>Grep-&grep-version;</title>
 <?dbhtml filename="grep.html"?>
 
+<indexterm zone="ch-tools-grep">
+<primary sortas="a-Grep">Grep</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/grep.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.1 SBU</seg><seg>5.8 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/grep.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -25,12 +32,32 @@
 <screen><userinput>./configure --prefix=/tools \
     --disable-perl-regexp --with-included-regex</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--disable-perl-regexp</parameter></term>
+<listitem><para>This makes sure that the <command>grep</command>
+program does not get linked against a Perl Compatible Regular
+Expression (PCRE) library that may be present on the host and would
+not be available once we enter the chroot
+environment.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--with-included-regex</parameter></term>
+<listitem><para>This ensures that Grep uses its internal regular
+expression code.  Without this switch, Grep will use the code from
+Glibc, which is known to be buggy.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
 <para>Install the package:</para>
 
@@ -38,4 +65,10 @@
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-grep" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/gzip.xml b/chapter05/gzip.xml
index f8c86b663..3683d5ff9 100644
--- a/chapter05/gzip.xml
+++ b/chapter05/gzip.xml
@@ -7,7 +7,12 @@
 <title>Gzip-&gzip-version;</title>
 <?dbhtml filename="gzip.html"?>
 
+<indexterm zone="ch-tools-gzip">
+<primary sortas="a-Gzip">Gzip</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gzip.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.1 SBU</seg><seg>2.6 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gzip.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,10 +35,18 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>And install it:</para>
+<para>This package does not come with a test suite.</para>
+
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-gzip" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/hostreqs.xml b/chapter05/hostreqs.xml
index c4a216a24..310d450d1 100644
--- a/chapter05/hostreqs.xml
+++ b/chapter05/hostreqs.xml
@@ -7,6 +7,34 @@
 <title>Host System Requirements</title>
 <?dbhtml filename="hostreqs.html"?>
 
-<para>See testing.</para>
+<para>The host must be running at least a 2.6.2 kernel compiled with
+GCC-3.0 or higher. There are two main reasons for this high
+requirement. First, the Native POSIX Threading Library (NPTL)
+test suite will segfault if the host's kernel has not been compiled with
+GCC-3.0 or a later version. Secondly, the 2.6.2 or later version of
+the kernel is required for the use of Udev. Udev creates devices
+dynamically by reading from the <systemitem
+class="filesystem">sysfs</systemitem> file system. However, support
+for this filesystem has only recently been implemented in most of
+the kernel drivers. We must be sure that all critical system devices
+get created properly.</para>
+
+<para>In order to determine whether the host kernel meets the
+requirements outlined above, run the following command:</para>
+
+<screen><userinput>cat /proc/version</userinput></screen>
+
+<para>This will produce output similar to:</para>
+
+<screen><computeroutput>Linux version 2.6.2 (user@host) (gcc version 3.4.0) #1
+    Tue Apr 20 21:22:18 GMT 2004</computeroutput></screen>
+
+<para>If the results of the above command state that the host kernel
+was not compiled using a GCC-3.0 (or later) compiler, one will need to
+be compiled.  The host system will then need to be rebooted to use the
+newly compiled kernel. Instructions for compiling the kernel and
+configuring the boot loader (assuming the host uses GRUB) are located
+in <xref linkend="chapter-bootable"/>.</para>
 
 </sect1>
+
diff --git a/chapter05/introduction.xml b/chapter05/introduction.xml
index e16f460a8..4438bd7a6 100644
--- a/chapter05/introduction.xml
+++ b/chapter05/introduction.xml
@@ -7,6 +7,61 @@
 <title>Introduction</title>
 <?dbhtml filename="introduction.html"?>
 
-<para>See testing.</para>
+<para>This chapter shows how to compile and install a minimal Linux
+system. This system will contain just enough tools to start
+constructing the final LFS system in <xref
+linkend="chapter-building-system"/> and allow a working environment
+with more user convenience than a minimum environment would.</para>
+
+<para>There are two steps in building this minimal system. The first
+step is to build a new and host-independent toolchain (compiler,
+assembler, linker, libraries, and a few useful utilities).  The second
+step uses this toolchain to build the other essential tools.</para>
+
+<para>The files compiled in this chapter will be installed under the
+<filename class="directory">$LFS/tools</filename> directory to keep
+them separate from the files installed in the next chapter and the
+host production directories. Since the packages compiled here are
+temporary, we do not want them to pollute the soon-to-be LFS
+system.</para>
+
+<para>Before issuing the build instructions for a package, the package
+should be unpacked as user <emphasis>lfs</emphasis>, and a
+<command>cd</command> into the created directory should be performed. The build
+instructions assume that the <command>bash</command> shell is in use.</para>
+
+<para>Several of the packages are patched before compilation, but only
+when the patch is needed to circumvent a problem. A patch is often
+needed in both this and the next chapter, but sometimes in only one or
+the other. Therefore, do not be concerned if instructions for a downloaded
+patch seem to be missing. Warning messages about
+<emphasis>offset</emphasis> or <emphasis>fuzz</emphasis> may
+also be encountered when applying a patch. Do not worry about these
+warnings, as the patch was still successfully applied.</para>
+
+<para>During the compilation of most packages, there will be several
+warnings that scroll by on the screen. These are normal and can safely
+be ignored. These warnings are as they appear&mdash;warnings about
+deprecated, but not invalid, use of the C or C++ syntax. C standards
+change fairly often, and some packages still use the older standard.
+This is not a problem, but does prompt the warning.</para>
+
+<para>After installing each package, delete its source and build
+directories, unless specifically instructed otherwise. Deleting the
+sources saves space and prevents mis-configuration when the same
+package is reinstalled later. Only three of the packages need to
+retain the source and build directories in order for their contents to
+be used by later commands. Pay special attention to these
+reminders.</para>
+
+<para>Check one last time that the <envar>LFS</envar> environment 
+variable is set up properly:</para>
+
+<screen><userinput>echo $LFS</userinput></screen>
+
+<para>Make sure the output shows the path to the LFS partition's mount
+point, which is <filename class="directory">/mnt/lfs</filename>, using
+our example.</para>
 
 </sect1>
+
diff --git a/chapter05/linux-libc-headers.xml b/chapter05/linux-libc-headers.xml
index 167dceb57..4370bef9f 100644
--- a/chapter05/linux-libc-headers.xml
+++ b/chapter05/linux-libc-headers.xml
@@ -7,7 +7,14 @@
 <title>Linux-Libc-Headers-&linux-libc-headers-version;</title>
 <?dbhtml filename="linux-libc-headers.html"?>
 
+<indexterm zone="ch-tools-linux-libc-headers">
+<primary sortas="a-Linux-Libc-Headers">Linux-Libc-Headers</primary>
+<secondary>tools, headers</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude"
+	href="../chapter06/linux-libc-headers.xml"
+	xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,16 +22,38 @@
 <seglistitem><seg>0.1 SBU</seg><seg>22 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude"
+	href="../chapter06/linux-libc-headers.xml"
+	xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Linux-Libc-Headers</title>
 
+<para>For years it has been common practice to use <quote>raw</quote> kernel
+headers (straight from a kernel tarball) in <filename
+class="directory">/usr/include</filename>, but over the
+last few years, the kernel developers have taken a strong stance that
+this should not be done. This gave birth to the Linux-Libc-Headers
+Project, which was designed to maintain an Application Programming
+Interface (API) stable version of the Linux headers.</para>
+
 <para>Install the header files:</para>
 
 <screen><userinput>cp -R include/asm-i386 /tools/include/asm
 cp -R include/linux /tools/include</userinput></screen>
 
+<para>If your architecture is not i386 (compatible), adjust the first command
+accordingly.</para>
+
+</sect2>
+
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-linux-libc-headers" role="."/></para>
 </sect2>
 
 </sect1>
+
diff --git a/chapter05/m4.xml b/chapter05/m4.xml
index bab2b6a18..c861f0593 100644
--- a/chapter05/m4.xml
+++ b/chapter05/m4.xml
@@ -3,11 +3,16 @@
   <!ENTITY % general-entities SYSTEM "../general.ent">
   %general-entities;
 ]>
-<sect1 id="ch-tools-m4" xreflabel="M4" role="wrap">
+<sect1 id="ch-tools-m4" role="wrap">
 <title>M4-&m4-version;</title>
 <?dbhtml filename="m4.html"?>
 
+<indexterm zone="ch-tools-m4">
+<primary sortas="a-M4">M4</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/m4.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.1 SBU</seg><seg>3.0 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/m4.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,13 +35,19 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results, issue:
-<userinput>make check</userinput>.</para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
-<para>Now install the package:</para>
+<para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-m4" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/make.xml b/chapter05/make.xml
index ea37ca105..d20b8ac0a 100644
--- a/chapter05/make.xml
+++ b/chapter05/make.xml
@@ -7,7 +7,12 @@
 <title>Make-&make-version;</title>
 <?dbhtml filename="make.html"?>
 
+<indexterm zone="ch-tools-make">
+<primary sortas="a-Make">Make</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/make.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>8.8 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/make.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,8 +35,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results,  issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
 <para>Install the package:</para>
 
@@ -37,4 +44,10 @@
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-make" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/ncurses.xml b/chapter05/ncurses.xml
index 8227b03bb..72538b445 100644
--- a/chapter05/ncurses.xml
+++ b/chapter05/ncurses.xml
@@ -7,7 +7,12 @@
 <title>Ncurses-&ncurses-version;</title>
 <?dbhtml filename="ncurses.html"?>
 
+<indexterm zone="ch-tools-ncurses">
+<primary sortas="a-Ncurses">Ncurses</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/ncurses.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.7 SBU</seg><seg>26 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/ncurses.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -25,14 +32,43 @@
 <screen><userinput>./configure --prefix=/tools --with-shared \
     --without-debug --without-ada --enable-overwrite</userinput></screen>
 
+<para>The meaning of the configure options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>--without-ada</parameter></term>
+<listitem><para>This tells Ncurses not to build its Ada bindings, even
+if an Ada compiler is installed on the host. This needs to be done
+because once we enter the chroot environment, Ada will no longer be
+available.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>--enable-overwrite</parameter></term>
+<listitem><para>This tells Ncurses to install its header files into
+<filename class="directory">/tools/include</filename>, instead of
+<filename class="directory">/tools/include/ncurses</filename>, to
+ensure that other packages can find the Ncurses headers
+successfully.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
+<para>This package does not come with a test suite.</para>
+
 <para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-ncurses" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/patch.xml b/chapter05/patch.xml
index 0f8c62cb5..ec5bc8888 100644
--- a/chapter05/patch.xml
+++ b/chapter05/patch.xml
@@ -7,7 +7,12 @@
 <title>Patch-&patch-version;</title>
 <?dbhtml filename="patch.html"?>
 
+<indexterm zone="ch-tools-patch">
+<primary sortas="a-Patch">Patch</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/patch.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.1 SBU</seg><seg>1.9 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/patch.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -24,14 +31,26 @@
 
 <screen><userinput>CPPFLAGS=-D_GNU_SOURCE ./configure --prefix=/tools</userinput></screen>
 
+<para>The preprocessor flag <parameter>-D_GNU_SOURCE</parameter> is
+only needed on the PowerPC platform. It can be left out on other
+architectures.</para>
+
 <para>Compile the package:</para>
 
 <screen><userinput>make</userinput></screen>
 
+<para>This package does not come with a test suite.</para>
+
 <para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-patch" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/perl.xml b/chapter05/perl.xml
index d118bb56f..77d619441 100644
--- a/chapter05/perl.xml
+++ b/chapter05/perl.xml
@@ -7,7 +7,12 @@
 <title>Perl-&perl-version;</title>
 <?dbhtml filename="perl.html"?>
 
+<indexterm zone="ch-tools-perl">
+<primary sortas="a-Perl">Perl</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/perl.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,24 +20,45 @@
 <seglistitem><seg>0.8 SBU</seg><seg>74 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/perl.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Perl</title>
 
-<para>First adapt some hard-wired paths to the C library:</para>
+<para>First adapt some hard-wired paths to the C library by applying
+the following patch:</para>
 
 <screen><userinput>patch -Np1 -i ../perl-&perl-version;-libc-1.patch</userinput></screen>
 
-<para>Now prepare Perl for compilation:</para>
+<para>Prepare Perl for compilation (make sure to get the 'IO Fcntl POSIX'
+part of the command correct&mdash;they are all letters):</para>
 
 <screen><userinput>./configure.gnu --prefix=/tools -Dstatic_ext='IO Fcntl POSIX'</userinput></screen>
 
+<para>The meaning of the configure option:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>-Dstatic_ext='IO Fcntl POSIX'</parameter></term>
+<listitem><para>This tells Perl to build the minimum set of static
+extensions needed for installing and testing the Coreutils package in
+the next chapter.</para></listitem>
+</varlistentry>
+</variablelist>
+
 <para>Compile only the required tools:</para>
 
 <screen><userinput>make perl utilities</userinput></screen>
 
-<para>Then copy these tools and their libraries:</para>
+<para>Although Perl comes with a test suite, it is not recommended to
+run it at this point. Only part of Perl was built and running
+<userinput>make test</userinput> now will cause the rest of Perl to be
+built as well, which is unnecessary at this point. The test suite can
+be run in the next chapter if desired.</para>
+
+<para>Copy these tools and their libraries:</para>
 
 <screen><userinput>cp perl pod/pod2man /tools/bin
 mkdir -p /tools/lib/perl5/&perl-version;
@@ -40,4 +66,10 @@ cp -R lib/* /tools/lib/perl5/&perl-version;</userinput></screen>
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-perl" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/sed.xml b/chapter05/sed.xml
index 271e01d4d..9bb1090e4 100644
--- a/chapter05/sed.xml
+++ b/chapter05/sed.xml
@@ -7,7 +7,12 @@
 <title>Sed-&sed-version;</title>
 <?dbhtml filename="sed.html"?>
 
+<indexterm zone="ch-tools-sed">
+<primary sortas="a-Sed">Sed</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/sed.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>5.2 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/sed.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,8 +35,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results,  issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
 <para>Install the package:</para>
 
@@ -37,4 +44,10 @@
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-sed" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/stripping.xml b/chapter05/stripping.xml
index 5e7d7a00a..dcafa39da 100644
--- a/chapter05/stripping.xml
+++ b/chapter05/stripping.xml
@@ -7,13 +7,32 @@
 <title>Stripping</title>
 <?dbhtml filename="stripping.html"?>
 
-<para>Strip the programs and libraries:</para>
+<para>The steps in this section are optional, but if the LFS partition
+is rather small, it is beneficial to learn that unnecessary items can
+be removed. The executables and libraries built so far contain about
+130 MB of unneeded debugging symbols. Remove those symbols
+with:</para>
 
 <screen><userinput>strip --strip-debug /tools/lib/*
 strip --strip-unneeded /tools/{,s}bin/*</userinput></screen>
 
-<para>Remove the documentation:</para>
+<para>The last of the above commands will skip some twenty files,
+reporting that it does not recognize their file format. Most of these
+are scripts instead of binaries.</para>
+
+<para>Take care <emphasis>not</emphasis> to use
+<parameter>--strip-unneeded</parameter> on the libraries.  The static
+ones would be destroyed and the toolchain packages would need to be
+built all over again.</para>
+
+<para>To save another 30 MB, remove the documentation:</para>
 
 <screen><userinput>rm -rf /tools/{doc,info,man}</userinput></screen>
 
+<para>There will now be at least 850 MB of free space on the LFS file
+system that can be used to build and install Glibc in the next phase.
+If you can build and install Glibc, you can build and install the rest
+too.</para>
+
 </sect1>
+
diff --git a/chapter05/tar.xml b/chapter05/tar.xml
index bd279bada..21e59b24c 100644
--- a/chapter05/tar.xml
+++ b/chapter05/tar.xml
@@ -7,7 +7,12 @@
 <title>Tar-&tar-version;</title>
 <?dbhtml filename="tar.html"?>
 
+<indexterm zone="ch-tools-tar">
+<primary sortas="a-Tar">Tar</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/tar.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>10 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/tar.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,8 +35,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results,  issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
 <para>Install the package:</para>
 
@@ -37,4 +44,10 @@
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-tar" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/tcl.xml b/chapter05/tcl.xml
index 7f15832c2..69dcbdec3 100644
--- a/chapter05/tcl.xml
+++ b/chapter05/tcl.xml
@@ -3,13 +3,14 @@
   <!ENTITY % general-entities SYSTEM "../general.ent">
   %general-entities;
 ]>
-<sect1 id="ch-tools-tcl" xreflabel="Tcl" role="wrap">
+<sect1 id="ch-tools-tcl" role="wrap">
 <title>Tcl-&tcl-version;</title>
 <?dbhtml filename="tcl.html"?>
 
 <indexterm zone="ch-tools-tcl"><primary sortas="a-Tcl">Tcl</primary></indexterm>
 
 <sect2 role="package"><title/>
+<para>The Tcl package contains the Tool Command Language.</para>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -17,11 +18,26 @@
 <seglistitem><seg>0.9 SBU</seg><seg>23 MB</seg></seglistitem>
 </segmentedlist>
 
+<segmentedlist>
+<segtitle>Tcl installation depends on</segtitle>
+<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils,
+GCC, Glibc, Grep, Make, and Sed</seg></seglistitem>
+</segmentedlist>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Tcl</title>
 
+<para>This package and the next two (Expect and DejaGNU) are
+installed to support running the test suites for GCC and Binutils.
+Installing three packages for testing purposes may seem excessive, but
+it is very reassuring, if not essential, to know that the most
+important tools are working properly. Even if the test suites are not
+run in this chapter (they are not mandatory), these packages
+are required to run the test suites in <xref
+linkend="chapter-building-system"/>.</para>
+
 <para>Prepare Tcl for compilation:</para>
 
 <screen><userinput>cd unix
@@ -31,14 +47,22 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results,  issue:
-<userinput>TZ=UTC make test</userinput>.</para>
+<para>To test the results, issue: <userinput>TZ=UTC make
+test</userinput>. The Tcl test suite is known to experience failures
+under certain host conditions that are not fully understood.
+Therefore, test suite failures here are not surprising, and are not
+considered critical. The <parameter>TZ=UTC</parameter> parameter sets
+the time zone to Coordinated Universal Time (UTC), also known as
+Greenwich Mean Time (GMT), but only for the duration of the test suite
+run. This ensures that the clock tests are exercised correctly.
+Details on the <envar>TZ</envar> environment variable is provided in
+<xref linkend="chapter-bootscripts"/>.</para>
 
 <para>Install the package:</para>
 
 <screen><userinput>make install</userinput></screen>
 
-<warning><para><emphasis>Do not remove</emphasis> the
+<warning><para><emphasis>Do not</emphasis> remove the
 <filename class="directory">tcl&tcl-version;</filename> source directory yet, as the next package
 will need its internal headers.</para></warning>
 
@@ -50,8 +74,41 @@ will need its internal headers.</para></warning>
 
 <sect2 id="contents-tcl" role="content"><title>Contents of Tcl</title>
 
-<para>See testing</para>
+<segmentedlist>
+<segtitle>Installed programs</segtitle>
+<segtitle>Installed library</segtitle>
+<seglistitem><seg>tclsh (link to tclsh8.4) and tclsh8.4</seg><seg>libtcl8.4.so</seg></seglistitem>
+</segmentedlist>
+
+<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead>
+<?dbfo list-presentation="list"?>
+
+<varlistentry id="tclsh8.4">
+<term><command>tclsh8.4</command></term>
+<listitem>
+<para>The Tcl command shell</para>
+<indexterm zone="ch-tools-tcl tclsh8.4"><primary sortas="b-tclsh8.4">tclsh8.4</primary></indexterm>
+</listitem>
+</varlistentry>
+
+<varlistentry id="tclsh">
+<term><command>tclsh</command></term>
+<listitem>
+<para>A link to tclsh8.4</para>
+<indexterm zone="ch-tools-tcl tclsh"><primary sortas="b-tclsh">tclsh</primary></indexterm>
+</listitem>
+</varlistentry>
+
+<varlistentry id="libtcl8.4.so">
+<term><filename class="libraryfile">libtcl8.4.so</filename></term>
+<listitem>
+<para>The Tcl library</para>
+<indexterm zone="ch-tools-tcl libtcl8.4.so"><primary sortas="c-libtcl8.4.so">libtcl8.4.so</primary></indexterm>
+</listitem>
+</varlistentry>
+</variablelist>
 
 </sect2>
 
 </sect1>
+
diff --git a/chapter05/texinfo.xml b/chapter05/texinfo.xml
index dce70c00b..3a7ddf4c6 100644
--- a/chapter05/texinfo.xml
+++ b/chapter05/texinfo.xml
@@ -7,7 +7,12 @@
 <title>Texinfo-&texinfo-version;</title>
 <?dbhtml filename="texinfo.html"?>
 
+<indexterm zone="ch-tools-texinfo">
+<primary sortas="a-Texinfo">Texinfo</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/texinfo.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,6 +20,8 @@
 <seglistitem><seg>0.2 SBU</seg><seg>16 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/texinfo.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
@@ -28,8 +35,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>To test the results,  issue:
-<userinput>make check</userinput></para>
+<para>To test the results, issue: <userinput>make
+check</userinput>.</para>
 
 <para>Install the package:</para>
 
@@ -37,4 +44,10 @@
 
 </sect2>
 
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-texinfo" role="."/></para>
+</sect2>
+
 </sect1>
+
diff --git a/chapter05/toolchaintechnotes.xml b/chapter05/toolchaintechnotes.xml
index afc621085..9c2951387 100644
--- a/chapter05/toolchaintechnotes.xml
+++ b/chapter05/toolchaintechnotes.xml
@@ -7,6 +7,218 @@
 <title>Toolchain Technical Notes</title>
 <?dbhtml filename="toolchaintechnotes.html"?>
 
-<para>See testing</para>
+<para>This section explains some of the rationale and technical
+details behind the overall build method. It is not essential to
+immediately understand everything in this section. Most of this
+information will be clearer after performing an actual build. This
+section can be referred back to at any time during the process.</para>
+
+<para>The overall goal of <xref linkend="chapter-temporary-tools"/> is
+to provide a temporary environment that can be chrooted into and from
+which can be produced a clean, trouble-free build of the target LFS
+system in <xref linkend="chapter-building-system"/>. Along the way, we
+separate from the host system as much as possible, and in doing so,
+build a self-contained and self-hosted toolchain. It should be noted
+that the build process has been designed to minimize the risks for new
+readers and provide maximum educational value at the same time. In
+other words, more advanced techniques could be used to build the
+system.</para>
+
+<important>
+<para>Before continuing, be aware of the name of the working platform,
+often referred to as the target triplet. Many times, the target
+triplet will probably be <emphasis>i686-pc-linux-gnu</emphasis>. A
+simple way to determine the name of the target triplet is to run the
+<command>config.guess</command> script that comes with the source for
+many packages. Unpack the Binutils sources and run the script:
+<userinput>./config.guess</userinput> and note the output.</para>
+
+<para>Also be aware of the name of the platform's dynamic linker,
+often referred to as the dynamic loader (not to be confused with the
+standard linker <command>ld</command> that is part of Binutils). The
+dynamic linker provided by Glibc finds and loads the shared libraries
+needed by a program, prepares the program to run, and then runs it.
+The name of the dynamic linker will usually be
+<filename class="libraryfile">ld-linux.so.2</filename>. On platforms that are less
+prevalent, the name might be <filename class="libraryfile">ld.so.1</filename>, 
+and newer 64 bit platforms might be named something else entirely. The name of
+the platform's dynamic linker can be determined by looking in the
+<filename class="directory">/lib</filename> directory on the host
+system. A sure-fire way to determine the name is to inspect a random
+binary from the host system by running: <userinput>readelf -l &lt;name
+of binary&gt; | grep interpreter</userinput> and noting the output.
+The authoritative reference covering all platforms is in the
+<filename>shlib-versions</filename> file in the root of the Glibc
+source tree.</para>
+</important>
+
+<para>Some key technical points of how the <xref linkend="chapter-temporary-tools"/> build
+method works:</para>
+
+<itemizedlist>
+<listitem><para>The process is similar in principle to
+cross-compiling, whereby tools installed in the same prefix work in
+cooperation, and thus utilize a little GNU
+<quote>magic</quote></para></listitem>
+
+<listitem><para>Careful manipulation of the standard linker's library
+search path ensures programs are linked only against chosen
+libraries</para></listitem>
+
+<listitem><para>Careful manipulation of <command>gcc</command>'s
+<filename>specs</filename> file tell the compiler which target dynamic
+linker will be used</para></listitem>
+</itemizedlist>
+
+<para>Binutils is installed first because the
+<command>./configure</command> runs of both GCC and Glibc perform
+various feature tests on the assembler and linker to determine which
+software features to enable or disable. This is more important than
+one might first realize. An incorrectly configured GCC or Glibc can
+result in a subtly broken toolchain, where the impact of such breakage
+might not show up until near the end of the build of an entire
+distribution. A test suite failure will usually alert this error
+before too much additional work is performed.</para>
+
+<para>Binutils installs its assembler and linker in two locations,
+<filename class="directory">/tools/bin</filename> and <filename
+class="directory">/tools/$TARGET_TRIPLET/bin</filename>. The tools in
+one location are hard linked to the other. An important facet of the
+linker is its library search order. Detailed information can be
+obtained from <command>ld</command> by passing it the
+<parameter>--verbose</parameter> flag. For example, an <userinput>ld
+--verbose | grep SEARCH</userinput> will illustrate the current search
+paths and their order. It shows which files are linked by
+<command>ld</command> by compiling a dummy program and passing the
+<parameter>--verbose</parameter> switch to the linker. For example,
+<userinput>gcc dummy.c -Wl,--verbose 2&gt;&amp;1 | grep
+succeeded</userinput> will show all the files successfully opened
+during the linking.</para>
+
+<para>The next package installed is GCC. An example of what can be
+seen during its run of <command>./configure</command> is:</para>
+
+<screen><computeroutput>checking what assembler to use... 
+        /tools/i686-pc-linux-gnu/bin/as
+checking what linker to use... /tools/i686-pc-linux-gnu/bin/ld</computeroutput></screen>
+
+<para>This is important for the reasons mentioned above. It also
+demonstrates that GCC's configure script does not search the PATH
+directories to find which tools to use. However, during the actual
+operation of <command>gcc</command> itself, the same
+search paths are not necessarily used. To find out which standard
+linker <command>gcc</command> will use, run: <userinput>gcc
+-print-prog-name=ld</userinput>.</para>
+
+<para>Detailed information can be obtained from <command>gcc</command>
+by passing it the <parameter>-v</parameter> command line option while
+compiling a dummy program. For example, <userinput>gcc -v
+dummy.c</userinput> will show detailed information about the
+preprocessor, compilation, and assembly stages, including
+<command>gcc</command>'s included search paths and their order.</para>
+
+<para>The next package installed is Glibc. The most important
+considerations for building Glibc are the compiler, binary tools, and
+kernel headers. The compiler is generally not an issue since Glibc
+will always use the <command>gcc</command> found in a 
+<envar>PATH</envar> directory.
+The binary tools and kernel headers can be a bit more complicated.
+Therefore, take no risks and use the available configure switches to
+enforce the correct selections. After the run of
+<command>./configure</command>, check the contents of the
+<filename>config.make</filename> file in the <filename
+class="directory">glibc-build</filename> directory for all important
+details. Note the use of <parameter>CC="gcc -B/tools/bin/"</parameter>
+to control which binary tools are used and the use of the
+<parameter>-nostdinc</parameter> and <parameter>-isystem</parameter>
+flags to control the compiler's include search path. These items
+highlight an important aspect of the Glibc package&mdash;it is very
+self-sufficient in terms of its build machinery and generally does not
+rely on toolchain defaults.</para>
+
+<para>After the Glibc installation, make some adjustments to ensure
+that searching and linking take place only within the <filename
+class="directory">/tools</filename> prefix.  Install an adjusted
+<command>ld</command>, which has a hard-wired search path limited to
+<filename class="directory">/tools/lib</filename>. Then amend
+<command>gcc</command>'s specs file to point to the new dynamic linker
+in <filename class="directory">/tools/lib</filename>. This last step
+is vital to the whole process. As mentioned above, a hard-wired path
+to a dynamic linker is embedded into every Executable and Link Format
+(ELF)-shared executable.  This can be inspected by running:
+<userinput>readelf -l &lt;name of binary&gt; | grep
+interpreter</userinput>. Amending gcc's specs file
+ensures that every program compiled from here through the end of this
+chapter will use the new dynamic linker in <filename
+class="directory">/tools/lib</filename>.</para>
+
+<para>The need to use the new dynamic linker is also the reason why
+the Specs patch is applied for the second pass of GCC. Failure to do
+so will result in the GCC programs themselves having the name of the
+dynamic linker from the host system's <filename
+class="directory">/lib</filename> directory embedded into them, which
+would defeat the goal of getting away from the host.</para> 
+
+<para>During the second pass of Binutils, we are able to utilize the
+<parameter>--with-lib-path</parameter> configure switch to control
+<command>ld</command>'s library search path.  From this point onwards,
+the core toolchain is self-contained and self-hosted. The remainder of
+the <xref linkend="chapter-temporary-tools"/> packages all build
+against the new Glibc in <filename
+class="directory">/tools</filename>.</para>
+
+<para>Upon entering the chroot environment in <xref
+linkend="chapter-building-system"/>, the first major package to be
+installed is Glibc, due to its self-sufficient nature mentioned above.
+Once this Glibc is installed into <filename
+class="directory">/usr</filename>, perform a quick changeover of the
+toolchain defaults, then proceed in building the rest of the target
+LFS system.</para>
+
+<sect2>
+<title>Notes on Static Linking</title>
+
+<para>Besides their specific task, most programs have to perform many
+common and sometimes trivial operations. These include allocating
+memory, searching directories, reading and writing files, string
+handling, pattern matching, arithmetic, and other tasks. Instead of
+obliging each program to reinvent the wheel, the GNU system provides
+all these basic functions in ready-made libraries. The major library
+on any Linux system is Glibc.</para>
+
+<para>There are two primary ways of linking the functions from a
+library to a program that uses them&mdash;statically or dynamically. When
+a program is linked statically, the code of the used functions is
+included in the executable, resulting in a rather bulky program. When
+a program is dynamically linked, it includes a reference to the
+dynamic linker, the name of the library, and the name of the function,
+resulting in a much smaller executable. A third option is to use the
+programming interface of the dynamic linker (see the
+<emphasis>dlopen</emphasis> man page for more information).</para>
+
+<para>Dynamic linking is the default on Linux and has three major
+advantages over static linking. First, only one copy of the executable
+library code is needed on the hard disk, instead of having multiple
+copies of the same code included in several programs, thus saving
+disk space. Second, when several programs use the same library
+function at the same time, only one copy of the function's code is
+required in core, thus saving memory space. Third, when a library
+function gets a bug fixed or is otherwise improved, only the one
+library needs to be recompiled instead of recompiling all programs
+that make use of the improved function.</para>
+
+<para>If dynamic linking has several advantages, why then do we
+statically link the first two packages in this chapter? The reasons
+are threefold&mdash;historical, educational, and technical. The
+historical reason is that earlier versions of LFS statically linked
+every program in this chapter. Educationally, knowing the difference
+between static and dynamic linking is useful. The technical benefit is
+a gained element of independence from the host, meaning that those
+programs can be used independently of the host system. However, it is
+worth noting that an overall successful LFS build can still be
+achieved when the first two packages are built dynamically.</para>
+
+</sect2>
 
 </sect1>
+
diff --git a/chapter05/udev.xml b/chapter05/udev.xml
deleted file mode 100644
index 0809dfd53..000000000
--- a/chapter05/udev.xml
+++ /dev/null
@@ -1,40 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-  <!ENTITY % general-entities SYSTEM "../general.ent">
-  %general-entities;
-]>
-<sect1 id="ch-tools-udev" role="wrap">
-<title>Udev-&udev-version;</title>
-<?dbhtml filename="udev.html"?>
-
-<sect2 role="package"><title/>
-
-<segmentedlist>
-<segtitle>&buildtime;</segtitle>
-<segtitle>&diskspace;</segtitle>
-<seglistitem><seg>0.2 SBU</seg><seg>5.2 MB</seg></seglistitem>
-</segmentedlist>
-
-</sect2>
-
-<sect2 role="installation">
-<title>Installation of Udev</title>
-
-<para>The following patch makes Udev respect the DESTDIR variable:</para>
-
-<screen><userinput>patch -Np1 -i ../udev-&udev-version;-DESTDIR-1.patch</userinput></screen>
-
-<para>Now compile Udev:</para>
-
-<screen><userinput>make prefix=/tools udevdir=/dev</userinput></screen>
-
-<para>Install the package:</para>
-
-<screen><userinput>make DESTDIR=/tools udevdir=/dev install</userinput></screen>
-
-<screen><userinput>cp ../udev-config-2.permissions /tools/etc/udev/permissions.d/00-lfs.permissions
-cp ../udev-config-1.rules /tools/etc/udev/rules.d/00-lfs.rules</userinput></screen>
-
-</sect2>
-
-</sect1>
diff --git a/chapter05/util-linux.xml b/chapter05/util-linux.xml
index 4349f326f..1c0ae3c19 100644
--- a/chapter05/util-linux.xml
+++ b/chapter05/util-linux.xml
@@ -7,7 +7,12 @@
 <title>Util-linux-&util-linux-version;</title>
 <?dbhtml filename="util-linux.html"?>
 
+<indexterm zone="ch-tools-util-linux">
+<primary sortas="a-Util-linux">Util-linux</primary>
+<secondary>tools</secondary></indexterm>
+
 <sect2 role="package"><title/>
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/util-linux.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>
 
 <segmentedlist>
 <segtitle>&buildtime;</segtitle>
@@ -15,12 +20,16 @@
 <seglistitem><seg>0.2 SBU</seg><seg>16 MB</seg></seglistitem>
 </segmentedlist>
 
+<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/util-linux.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>
+
 </sect2>
 
 <sect2 role="installation">
 <title>Installation of Util-linux</title>
 
-<para>Issue a sed sustitution:</para>
+<para>Util-linux does not use the freshly installed headers and
+libraries from the <filename class="directory">/tools</filename>
+directory. This is fixed by altering the configure script:</para>
 
 <screen><userinput>sed -i 's@/usr/include@/tools/include@g' configure</userinput></screen>
 
@@ -32,14 +41,23 @@
 
 <screen><userinput>make -C lib</userinput></screen>
 
-<para>Build the needed utilities:</para>
+<para>Since only a couple of the utilities contained in this package
+are needed, build only those:</para>
 
 <screen><userinput>make -C mount mount umount
 make -C text-utils more</userinput></screen>
 
-<para>Now copy these programs to the temporary tools directory:</para>
+<para>This package does not come with a test suite.</para>
+
+<para>Copy these programs to the temporary tools directory:</para>
 
 <screen><userinput>cp mount/{,u}mount text-utils/more /tools/bin</userinput></screen>
 
 </sect2>
+
+<sect2 role="content"><title/>
+<para>Details on this package are located in <xref
+linkend="contents-utillinux" role="."/></para>
+</sect2>
 </sect1>
+