Adding some markup, and other brush-ups.

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

chapter01/changelog.xml

@@ -104,6 +104,9 @@ fix an extraneous whitespace problem in "tidy generated" web site pages.
 Essentially replace all ocurrences of <para><screen> with
 &lt;screen&gt; (and the matching closing tags).</para></listitem>
 
+<listitem><para>October 9th, 2003 [alex]: Chapter 6 - Basic Networking: Moved
+one half to the Lfs-Utils section, the other half to Perl.</para></listitem>
+ 
 <listitem><para>October 8th, 2003 [alex]: Chapter 8 - Making bootable: Adapted
 the style of the screens, and reworded some paragraphs.</para></listitem>
  
@@ -147,13 +150,13 @@ so removed those too.</para></listitem>
 <listitem><para>October 2nd, 2003 [greg]: Chapter 6 - Shadow: Enabled
 MD5 passwords. Closes Bug 600.</para></listitem>
 
-<listitem><para>September 27th, 2003 [greg]: Chapter 5 - Expect: Tweak install
+<listitem><para>September 27th, 2003 [greg]: Chapter 5 - Expect: Tweaked
-so that redundant scripts are not installed. Chapter 6 - Creating essential
+install so that redundant scripts are not installed. Chapter 6 - Creating
-symlinks: Remove redundant links. Chapter 6 - man: Remove PATH, closes
+essential symlinks: Removed redundant links. Chapter 6 - man: Removed PATH,
-Bug 574.</para></listitem>
+closes Bug 574.</para></listitem>
 
-<listitem><para>September 27th, 2003 [greg]: Add Tcl, Expect and DejaGnu items
+<listitem><para>September 27th, 2003 [greg]: Added Tcl, Expect and DejaGnu
-to Appendix A. Closes Bug 661.</para></listitem>
+items to Appendix A. Closes Bug 661.</para></listitem>
 
 <listitem><para>September 26th, 2003 [jeremy]: Added new workaround for the
 devpts problems.</para></listitem>
@@ -167,7 +170,7 @@ the short descriptions, and the content of most of them too.</para></listitem>
 <listitem><para>September 22nd, 2003 [greg]: Chapter 8 - Creating the /etc/fstab
 file: Made mounting devpts the default.</para></listitem>
 
-<listitem><para>September 22nd, 2003 [jeremy]: Added net-tools patch to fix
+<listitem><para>September 22nd, 2003 [jeremy]: Added Net-tools patch to fix
 mii-tool compilation.</para></listitem>
 
 <listitem><para>September 22nd, 2003 [jwrober]: Chapter 5 - Updated the Why 
@@ -187,8 +190,8 @@ man hint to a pointer to BLFS.</para></listitem>
 <listitem><para>September 22nd, 2003 [jeremy]: Added a note to remember to
 mount devpts if you exit and re-enter chroot.</para></listitem>
 
-<listitem><para>September 22nd, 2003 [jeremy]: removed make check from patch
+<listitem><para>September 22nd, 2003 [jeremy]: Removed make check from Patch
-and diffutils, since these tests perform no actions.</para></listitem>
+and Diffutils, since these tests perform no actions.</para></listitem>
 
 <listitem><para>September 22nd, 2003 [greg]: Chapter 5 - Setting up the
 environment: Added unset CC CXX CPP LD_LIBRARY_PATH LD_PRELOAD to
@@ -204,8 +207,8 @@ use of the +h flag to bash.</para></listitem>
 <listitem><para>September 19th, 2003 [jwrober]: Various updates to the 
 acknowledgements page.</para></listitem>
 
-<listitem><para>September 18th, 2003 [jeremy]: Chapter 5 - GCC Pass 2 -
+<listitem><para>September 18th, 2003 [jeremy]: Chapter 5 - GCC Pass 2: Added
-added some extra comments regarding the 3 tarballs to unpack.</para></listitem>
+some extra comments regarding the 3 tarballs to unpack.</para></listitem>
 
 <listitem><para>September 17th, 2003 [greg]: Chapter 6 - GCC-2.95.3: Added
 rationale notes.</para></listitem>
@@ -215,7 +218,7 @@ page to match the website.</para></listitem>
 
 <listitem><para>September 17th, 2003 [jeremy]: Upgraded File to 4.04.</para></listitem>
 
-<listitem><para>September 17th, 2003 [jeremy]: Chapter 6 - changed 2 of the
+<listitem><para>September 17th, 2003 [jeremy]: Chapter 6 - Changed 2 of the
 occurrences of exec bash --login to include the +h directive. </para></listitem>
 
 <listitem><para>September 17th, 2003 [greg]: Chapters 5 and 6 - Locking in

chapter05/binutils-pass2-inst.xml

@@ -3,10 +3,6 @@
 <sect2>
 <title>Re-installation of Binutils</title>
 
-<note><para>It's worth pointing out that the Binutils test suite we run in this
-section is considered not as important as the one we run in Chapter 6.</para>
-</note>
-
 <para>Create a separate build directory again:</para>
 
 <screen><userinput>mkdir ../binutils-build

chapter05/chapter05.xml

@@ -61,8 +61,9 @@ documentation:</para>
 
 <screen><userinput>rm -rf /tools/{,share/}{doc,info,man}</userinput></screen>
 
-<para>You will now need to have at least 700 MB of free space on your LFS
+<para>You will now need to have at least 800 MB of free space on your LFS
-filesystem to be able to build and install Glibc in the next phase.</para>
+filesystem to be able 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>
 

chapter05/gcc-pass2-inst.xml

@@ -107,6 +107,9 @@ needed to ensure that both C and C++ compilers are built.</para></listitem>
 as the compiler we're using to compile this GCC was built from the exact same
 version of the GCC sources we used earlier.</para>
 
+<note><para>It's worth pointing out that running the GCC test suite here
+is considered not as important running it in Chapter 6.</para></note>
+
 <para>Test the results:</para>
 
 <screen><userinput>make -k check</userinput></screen>
@@ -155,7 +158,7 @@ to continue on.</para>
 <note><para>At this point it is strongly recommended to repeat the sanity check
 we performed earlier in the chapter. Refer back to
 <xref linkend="ch05-locking-glibc"/> and repeat the check. If the results are
-wrong then most likely, you forgot to apply the above mentioned GCC Specs
+wrong, then most likely you forgot to apply the above mentioned GCC Specs
 patch.</para></note>
 
 </sect2>

chapter05/glibc-inst.xml

@@ -9,8 +9,8 @@ Glibc-linuxthreads in that directory, not in the directory where you usually
 unpack all the sources.</para>
 
 <note><para>We are going to run the test suite for Glibc in this chapter.
-However, it's worth pointing out that the Glibc test suite we run in this
+However, it's worth pointing out that running the Glibc test suite here 
-section is considered not as important as the one we run in Chapter 6.</para></note>
+is considered not as important as running it in Chapter 6.</para></note>
 
 <para>This package is known to behave badly when you have changed its
 default optimization flags (including the -march and -mcpu options).
@@ -89,7 +89,7 @@ running the test suite.</para>
 <screen><userinput>make check</userinput></screen>
 
 <para>The Glibc test suite is highly dependent on certain functions of your host
-system, in particular the kernel. Additionally, here in Chapter 5, some tests
+system, in particular the kernel. Additionally, here in Chapter 5 some tests
 can be adversely affected by existing tools or environmental issues on the host
 system. Of course, these won't be a problem when we run the Glibc test suite
 inside the chroot environment of Chapter 6. In general, the Glibc test suite is
@@ -98,34 +98,36 @@ unavoidable in certain circumstances. Here is a list of the most common issues
 we are aware of:</para>
 
 <itemizedlist>
-<listitem><para>The math tests sometimes fail when running on systems where the 
+<listitem><para>The <emphasis>math</emphasis> tests sometimes fail when running
-CPU is not a relatively new genuine Intel or genuine AMD. Certain optimization
+on systems where the CPU is not a relatively new genuine Intel or authentic AMD.
-settings are also known to be a factor here.</para></listitem>
+Certain optimization settings are also known to be a factor here.</para></listitem>
 
-<listitem><para>The gettext test sometimes fails due to host system issues. The
+<listitem><para>The <emphasis>gettext</emphasis> test sometimes fails due to
-exact reasons are not yet clear.</para></listitem>
+host system issues. The exact reasons are not yet clear.</para></listitem>
 
-<listitem><para>The atime test sometimes fails when the LFS partition is mounted
+<listitem><para>The <emphasis>atime</emphasis> test sometimes fails when the
-with the noatime option or due to other file system quirks.</para></listitem>
+LFS partition is mounted with the <emphasis>noatime</emphasis> option, or due
+to other file system quirks.</para></listitem>
 
-<listitem><para>In general, when running on slower hardware, some tests might
+<listitem><para>The <emphasis>shm</emphasis> test might fail when the host
+system is running the devfs file system but doesn't have the tmpfs file system
+mounted at <filename>/dev/shm</filename> due to lack of support for tmpfs in
+the kernel.</para></listitem>
+
+<listitem><para>When running on older and slower hardware, some tests might
 fail due to test timeouts being exceeded.</para></listitem>
-
-<listitem><para>The shm test might fail in the circumstances of the host system
-running the devfs file system but not having the tmpfs file system mounted at
-/dev/shm due to lack of support for tmpfs in the kernel.</para></listitem>
 </itemizedlist>
 
 <para>In summary, don't worry too much if you see Glibc test suite failures here
 in Chapter 5. The Glibc in Chapter 6 is the one we'll ultimately end up using so
 that is the one we would really like to see pass. But please keep in mind, even
-in Chapter 6 some failures could still occur, the math tests for example. When
+in Chapter 6 some failures could still occur -- the <emphasis>math</emphasis>
-experiencing a failure, note the failure then continue on by reissuing the
+tests for example. When experiencing a failure, make a note of it, then
-<userinput>make check</userinput>. The test suite should pick up where it left
+continue by reissuing the <userinput>make check</userinput>. The test suite
-off and continue on. You can circumvent this stop-start sequence by issuing a
+should pick up where it left off and continue on. You can circumvent this
-<userinput>make -k check</userinput>. But If you do that, be sure to log the
+stop-start sequence by issuing a <userinput>make -k check</userinput>. But if
-output so that you can later on peruse the log file and examine the total number
+you do that, be sure to log the output so that you can later peruse the log
-of failures.</para>
+file and examine the total number of failures.</para>
 
 <para>Now install the package:</para>
 
@@ -134,8 +136,8 @@ of failures.</para>
 <para>Different countries and cultures have varying conventions for how to
 communicate. These conventions range from very simple ones, such as the format
 for representing dates and times, to very complex ones, such as the language
-spoken. This "internationalization" works by means of locales. We'll install the
+spoken. The "internationalization" of GNU programs works by means of
-Glibc locales now:</para>
+<emphasis>locales</emphasis>. We'll install the Glibc locales now:</para>
 
 <screen><userinput>make localedata/install-locales</userinput></screen>
 
@@ -143,10 +145,10 @@ Glibc locales now:</para>
 those locales which you need or want. This can be achieved by using the
 <userinput>localedef</userinput> command. Information on this can be
 found in the <filename>INSTALL</filename> file in the
-<filename>glibc-&glibc-version;</filename> source. However, there are a
+<filename>glibc-&glibc-version;</filename> source. However, there are a number
-number of locales that are essential for the tests of future packages
+of locales that are essential for the tests of future packages to pass, in
-to pass correctly, in particular, the libstdc++ tests from GCC.  The following 
+particular, the <emphasis>libstdc++</emphasis> tests from GCC.  The following
-instructions, instead of the install-locales command above, will install 
+instructions, instead of the install-locales target above, will install
 the minimum set of locales necessary for the tests to run successfully:</para>
 
 <screen><userinput>mkdir -p /tools/lib/locale

chapter05/toolchaintechnotes.xml

@@ -13,9 +13,8 @@ build of the target LFS system in Chapter 6. Along the way, we attempt to
 divorce ourselves from the host system as much as possible, and in so doing
 build a self-contained and self-hosted toolchain. It should be noted that the
 build process has been designed in such a way so as to minimize the risks for
-new readers and also provide maximum educational value at the same time. In
+new readers and provide maximum educational value at the same time. In other
-other words, more advanced techniques could be used to achieve the same
+words, more advanced techniques could be used to build the system.</para>
-goals.</para>
 
 <important>
 <para>Before continuing, you really should be aware of the name of your working
@@ -56,93 +55,97 @@ into the same prefix work in cooperation and thus utilize a little GNU
 path to ensure programs are linked only against libraries we
 choose.</para></listitem>
 
-<listitem><para>Careful manipulation of GCC's <emphasis>specs</emphasis> file to
+<listitem><para>Careful manipulation of <userinput>gcc</userinput>'s
-tell GCC which target dynamic linker will be used.</para></listitem>
+<emphasis>specs</emphasis> file to tell the compiler which target dynamic
+linker will be used.</para></listitem>
 </itemizedlist>
 
 <para>Binutils is installed first because both GCC and Glibc perform various
 feature tests on the assembler and linker during their respective runs of
-<filename>./configure</filename> to determine which software features to enable
+<userinput>./configure</userinput> 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 a build of a whole
+of such breakage might not show up until near the end of the build of a whole
 distribution. Thankfully, a test suite failure will usually alert us before too
-much harm is done.</para>
+much time is wasted.</para>
 
 <para>Binutils installs its assembler and linker into two locations,
 <filename class="directory">/tools/bin</filename> and
 <filename class="directory">/tools/$TARGET_TRIPLET/bin</filename>. In reality,
-the tools in one location are hard linked to the other. An important facet of ld
+the tools in one location are hard linked to the other. An important facet of
-is its library search order. Detailed information can be obtained from ld by
+the linker is its library search order. Detailed information can be obtained
-passing it the <emphasis>--verbose</emphasis> flag. For example:
+from <userinput>ld</userinput> by passing it the <emphasis>--verbose</emphasis>
-<userinput>`ld --verbose | grep SEARCH`</userinput> will show you the current
+flag. For example: <userinput>`ld --verbose | grep SEARCH`</userinput> will
-search paths and order. You can see what files are actually linked by ld by
+show you the current search paths and their order. You can see what files are
-compiling a dummy program and passing the --verbose switch. For example:
+actually linked by <userinput>ld</userinput> by compiling a dummy program and
+passing the <emphasis>--verbose</emphasis> switch. For example:
 <userinput>`gcc dummy.c -Wl,--verbose 2>&amp;1 | grep succeeded`</userinput>
 will show you all the files successfully opened during the link.</para>
 
 <para>The next package installed is GCC and during its run of
-<filename>./configure</filename> you'll see, for example:</para>
+<userinput>./configure</userinput> you'll see, for example:</para>
 
 <blockquote><screen>checking what assembler to use... /tools/i686-pc-linux-gnu/bin/as
 checking what linker to use... /tools/i686-pc-linux-gnu/bin/ld</screen></blockquote>
 
 <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 GCC itself, the same
+tools to use. However, during the actual operation of <userinput>gcc</userinput>
-search paths are not necessarily used. You can find out which standard linker
+itself, the same search paths are not necessarily used. You can find out which
-GCC will use by running: <userinput>`gcc -print-prog-name=ld`</userinput>.
+standard linker <userinput>gcc</userinput> will use by running:
-Detailed information can be obtained from GCC by passing it the
+<userinput>`gcc -print-prog-name=ld`</userinput>.
-<emphasis>-v</emphasis> flag while compiling a dummy program. For example:
+Detailed information can be obtained from <userinput>gcc</userinput> by passing
-<userinput>`gcc -v dummy.c`</userinput> will show you detailed information about
+it the <emphasis>-v</emphasis> flag while compiling a dummy program. For
-the preprocessor, compilation and assembly stages, including GCC's include
+example: <userinput>`gcc -v dummy.c`</userinput> will show you detailed
-search paths and order.</para>
+information about the preprocessor, compilation and assembly stages, including
+<userinput>gcc</userinput>'s include 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 no problem as it will always use the GCC found in a $PATH
+is generally no problem as Glibc will always use the <userinput>gcc</userinput>
-directory. The binary tools and kernel headers can be a little more troublesome.
+found in a $PATH directory. The binary tools and kernel headers can be a little
-Therefore we take no risks and we use the available configure switches to
+more troublesome. Therefore we take no risks and use the available configure
-enforce the correct selections. After the run of
+switches to enforce the correct selections. After the run of
-<filename>./configure</filename> you can check the contents of the
+<userinput>./configure</userinput> you can check the contents of the
 <filename>config.make</filename> file in the
 <filename class="directory">glibc-build</filename> directory for all the
 important details. You'll note some interesting items like the use of
 <userinput>CC="gcc -B/tools/bin/"</userinput> to control which binary tools are
-used and also the use of the <emphasis>-nostdinc</emphasis> and
+used, and also the use of the <emphasis>-nostdinc</emphasis> and
-<emphasis>-isystem</emphasis> flags to control the GCC include search path.
+<emphasis>-isystem</emphasis> flags to control the compiler's include search
-These items help to highlight an important aspect of the Glibc package: it is
+path. These items help to highlight an important aspect of the Glibc package:
-very self sufficient in terms of its build machinery and generally does not rely
+it is very self-sufficient in terms of its build machinery and generally does
-on toolchain defaults.</para>
+not rely on toolchain defaults.</para>
 
 <para>After the Glibc installation, we make some adjustments to ensure that
-searching and linking take place only within our /tools prefix. We install an
+searching and linking take place only within our <filename>/tools</filename>
-adjusted ld, which has a hard-wired search path limited to
+prefix. We install an adjusted <userinput>ld</userinput>, which has a hard-wired
-<filename class="directory">/tools/lib</filename>. Then we amend GCC's specs
+search path limited to <filename class="directory">/tools/lib</filename>. Then
-file to point to our new dynamic linker in
+we amend <userinput>gcc</userinput>'s specs file to point to our new dynamic
-<filename class="directory">/tools/lib</filename>. This last step is
+linker in <filename class="directory">/tools/lib</filename>. This last step is
 <emphasis>vital</emphasis> to the whole process. As mentioned above, a
 hard-wired path to a dynamic linker is embedded into every ELF shared
 executable. You can inspect this by running:
 <userinput>`readelf -l &lt;name of binary&gt; | grep interpreter`</userinput>.
-By amending the GCC specs file, we are ensuring that every program compiled from
+By amending <userinput>gcc</userinput>'s specs file, we are ensuring that every
-here through the end of Chapter 5 will use our new dynamic linker in
+program compiled from here through the end of Chapter 5 will use our new
-<filename class="directory">/tools/lib</filename>.</para>
+dynamic linker in <filename class="directory">/tools/lib</filename>.</para>
 
 <para>The need to use the new dynamic linker is also the reason why we apply the
-specs patch for the second pass of GCC. Failure to do so will result in the GCC
+Specs patch for the second pass of GCC. Failure to do so will result in the GCC
-programs themselves having the dynamic linker from the host system's
+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 our goal of getting away from the host system.</para>
+would defeat our goal of getting away from the host.</para>
 
 <para>During the second pass of Binutils, we are able to utilize the
-<userinput>--with-lib-path</userinput> configure switch to control ld's library
+<emphasis>--with-lib-path</emphasis> configure switch to control
-search path. From this point onwards, the core toolchain is self-contained and
+<userinput>ld</userinput>'s library search path. From this point onwards, the
-self-hosted. The remainder of the Chapter 5 packages all build against the new
+core toolchain is self-contained and self-hosted. The remainder of the
-Glibc in <filename class="directory">/tools</filename> and all is well.</para>
+Chapter 5 packages all build against the new Glibc in
+<filename class="directory">/tools</filename> and all is well.</para>
 
 <para>Upon entering the chroot environment in Chapter 6, the first major package
-we install is Glibc, due to its self sufficient nature that we mentioned above.
+we install is Glibc, due to its self-sufficient nature that we mentioned above.
 Once this Glibc is installed into <filename class="directory">/usr</filename>,
 we perform a quick changeover of the toolchain defaults, then proceed for real
 in building the rest of the target Chapter 6 LFS system.</para>
@@ -163,9 +166,9 @@ program that uses them: 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, what
 is included is 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 way is
+the name of the function, resulting in a much smaller executable. (A third way
-to use the programming interface of the dynamic linker. See the
+is to use the programming interface of the dynamic linker. See the
-<emphasis>dlopen</emphasis> man page for more information.</para>
+<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, you need only one copy of the executable library

chapter06/gcc-inst.xml

@@ -70,9 +70,9 @@ compiler. To satisfy those packages, create a symlink:</para>
 <screen><userinput>ln -s gcc /usr/bin/cc</userinput></screen>
 
 <note><para>At this point it is strongly recommended to repeat the sanity check
-we performed earlier in the chapter. Refer back to
+we performed in the previous chapter. Refer back to
 <xref linkend="ch06-adjustingtoolchain"/> and repeat the check. If the results
-are wrong then most likely, you erroneously applied the GCC Specs patch from
+are wrong, then most likely you erroneously applied the GCC Specs patch from
 Chapter 5.</para></note>
 
 </sect2>