First half of fixes for Bug 675 - missing command descriptions.

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

chapter05/binutils-pass1-inst.xml

@@ -29,7 +29,7 @@ cd ../binutils-build</userinput></screen></para>
 <para><screen><userinput>../binutils-&binutils-version;/configure \
 &nbsp;&nbsp;&nbsp;&nbsp;--prefix=/tools --disable-nls</userinput></screen></para>
 
-<para>The meaning of the configure switches:</para>
+<para>The meaning of the configure options:</para>
 
 <itemizedlist>
 <listitem><para><userinput>--prefix=/tools</userinput>: This tells the
@@ -49,9 +49,11 @@ make LDFLAGS="-all-static"</userinput></screen></para>
 <para>The meaning of the make option:</para>
 
 <itemizedlist>
-<listitem><para><userinput>LDFLAGS="-all-static"</userinput>: This tells
-the linker that all the Binutils programs should be linked
-statically.</para></listitem>
+<listitem><para><userinput>LDFLAGS="-all-static"</userinput>: This tells the
+linker that all the Binutils programs should be linked statically. However,
+strictly speaking, <userinput>"-all-static"</userinput> is first passed on to
+the <emphasis>libtool</emphasis> program which then passes
+<userinput>"-static"</userinput> on to the linker.</para></listitem>
 </itemizedlist>
 
 <para>And install the package:</para>
@@ -63,6 +65,20 @@ statically.</para></listitem>
 <para><screen><userinput>make -C ld clean
 make -C ld LIB_PATH=/tools/lib</userinput></screen></para>
 
+<para>The meaning of the make options:</para>
+
+<itemizedlist>
+<listitem><para><userinput>-C ld clean</userinput>: This tells the make program
+to remove all the compiled files only in the <filename>ld</filename>
+subdirectory.</para></listitem>
+
+<listitem><para><userinput>-C ld LIB_PATH=/tools/lib</userinput>: This option
+rebuilds everything in the <filename>ld</filename> subdirectory. Specifying the
+LIB_PATH makefile variable on the command line allows us to override the default
+value and have it point to our temporary tools location. This preparation will
+be utilised later on in the chapter.</para></listitem>
+</itemizedlist>
+
 <caution><para>Do not yet remove the Binutils build and source
 directories. You will need them again in their current state a bit further on
 in this chapter.</para></caution>

chapter05/gcc-pass1-inst.xml

@@ -30,7 +30,7 @@ cd ../gcc-build</userinput></screen></para>
 &nbsp;&nbsp;&nbsp;&nbsp;--disable-nls --enable-shared \
 &nbsp;&nbsp;&nbsp;&nbsp;--enable-languages=c</userinput></screen></para>
 
-<para>The meaning of the new configure options:</para>
+<para>The meaning of the configure options:</para>
 
 <itemizedlist>
 <listitem><para><userinput>--with-local-prefix=/tools</userinput>:  The

chapter05/gcc-pass2-inst.xml

@@ -27,9 +27,9 @@ get PTYs working.</para>
 <note><para>It's worth pointing out that the GCC test suite we run in this
 section is considered not as important as the one we run in Chapter 6.</para></note>
 
-<para>Unpack all three GCC tarballs (-core, -g++, and -testsuite) in one and the same working directory.
-They will all unfold into a single <filename>gcc-&gcc-version;/</filename>
-subdir.</para>
+<para>Unpack all three GCC tarballs (-core, -g++, and -testsuite) in one and the
+same working directory. They will all unfold into a single
+<filename>gcc-&gcc-version;/</filename> subdirectory.</para>
 
 <para>First correct one problem and make an essential adjustment:</para>
 
@@ -74,6 +74,31 @@ variables that override the default optimization flags.</para>
 &nbsp;&nbsp;&nbsp;&nbsp;--enable-threads=posix --enable-__cxa_atexit \
 &nbsp;&nbsp;&nbsp;&nbsp;--enable-languages=c,c++</userinput></screen></para>
 
+<para>The meaning of the new configure options:</para>
+
+<itemizedlist>
+<listitem><para><userinput>--enable-threads=posix</userinput>: This enables
+C++ exception handling for multi-threaded code.</para></listitem>
+
+<listitem><para><userinput>--enable-__cxa_atexit</userinput>: This option
+allows use of __cxa_atexit, rather than atexit, to register C++ destructors for
+local statics and global objects and is essential for fully standards-compliant
+handling of destructors. It also affects the C++ ABI and therefore results in
+C++ shared libraries and C++ programs that are interoperable with other Linux
+distributions.</para></listitem>
+
+<listitem><para><userinput>--enable-clocale=gnu</userinput>: 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 model of <emphasis>gnu</emphasis>.
+However, people who don't install the <emphasis>de_DE</emphasis> locale, run the
+risk of building ABI incompatible C++ libraries due to the wrong locale model of
+<emphasis>generic</emphasis> being selected.</para></listitem>
+
+<listitem><para><userinput>--enable-languages=c,c++</userinput>: This option is
+needed to ensure that both C and C++ compilers are built.</para></listitem>
+</itemizedlist>
+
 <para>Compile the package:</para>
 
 <para><screen><userinput>make</userinput></screen></para>

chapter05/glibc-inst.xml

@@ -48,7 +48,7 @@ cd ../glibc-build</userinput></screen></para>
 &nbsp;&nbsp;&nbsp;&nbsp;--with-binutils=/tools/bin \
 &nbsp;&nbsp;&nbsp;&nbsp;--without-gd</userinput></screen></para>
 
-<para>The meaning of the new configure options:</para>
+<para>The meaning of the configure options:</para>
 
 <itemizedlist>
 <listitem><para><userinput>--disable-profile</userinput>: This disables the

chapter05/grep-inst.xml

@@ -8,7 +8,7 @@
 <para><screen><userinput>./configure --prefix=/tools \
 &nbsp;&nbsp;&nbsp;&nbsp;--disable-perl-regexp --with-included-regex</userinput></screen></para>
 
-<para>The meaning of the configure switches:</para>
+<para>The meaning of the configure options:</para>
 
 <itemizedlist>
 <listitem><para><userinput>--disable-perl-regexp</userinput>: This makes sure

chapter06/gcc-inst.xml

@@ -38,25 +38,6 @@ cd ../gcc-build</userinput></screen></para>
 &nbsp;&nbsp;&nbsp;&nbsp;--enable-__cxa_atexit --enable-clocale=gnu \
 &nbsp;&nbsp;&nbsp;&nbsp;--enable-languages=c,c++</userinput></screen></para>
 
-<para>The meaning of the new configure options:</para>
-
-<itemizedlist>
-<listitem><para><userinput>--enable-threads=posix</userinput>: This enables
-C++ exception handling for multi-threaded code.</para></listitem>
-
-<listitem><para><userinput>--enable-__cxa_atexit</userinput>: This option
-will result in C++ shared libraries and C++ programs that are interoperable
-with other Linux distributions.</para></listitem>
-
-<listitem><para><userinput>--enable-clocale=gnu</userinput>: There is a risk
-that some people will build ABI incompatible C++ libraries if they didn't
-install all of the glibc localedata. Using --enable-clocale=gnu ensures that
-the "right thing" is done in all cases. If you don't wish to use this option,
-then at least build the <emphasis>de_DE</emphasis> locale. When GCC finds
-this specific locale, then the correct locale mode (<emphasis>gnu</emphasis>)
-is implemented.</para></listitem>
-</itemizedlist>
-
 <para>Compile the package:</para>
 
 <para><screen><userinput>make</userinput></screen></para>

chapter06/glibc-inst.xml

@@ -34,16 +34,9 @@ cd ../glibc-build</userinput></screen></para>
 &nbsp;&nbsp;&nbsp;&nbsp;--disable-profile --enable-add-ons \
 &nbsp;&nbsp;&nbsp;&nbsp;--libexecdir=/usr/bin --with-headers=/usr/include</userinput></screen></para>
 
-<para>The meaning of the configure options:</para>
+<para>The meaning of the new configure options:</para>
 
 <itemizedlist>
-<listitem><para><userinput>--disable-profile</userinput>: This disables the
-building of the libraries with profiling information. Omit this option if you
-plan to do profiling.</para></listitem>
-
-<listitem><para><userinput>--enable-add-ons</userinput>: This enables any
-add-ons that we installed with Glibc, in our case Linuxthreads.</para></listitem>
-
 <listitem><para><userinput>--libexecdir=/usr/bin</userinput>: This will
 cause the <filename>pt_chown</filename> program to be installed in the
 <filename>/usr/bin</filename> directory.</para></listitem>
@@ -52,7 +45,7 @@ cause the <filename>pt_chown</filename> program to be installed in the
 ensures that the kernel headers in <filename>/usr/include</filename> are used
 for this build. If you don't pass this switch then the headers from
 <filename>/tools/include</filename> are used which of course is not ideal
-(although they should be identical). Using the switch has the advantage
+(although they should be identical). Using this switch has the advantage
 that you will be informed immediately should you have forgotten to install the
 kernel headers into <filename>/usr/include</filename>.</para></listitem>
 </itemizedlist>

chapter06/inetutils-inst.xml

@@ -23,10 +23,6 @@ prevents inetutils from installing the logger program, which is used by
 scripts to pass messages to the System Log Daemon. We do not install it
 because Util-linux installs a better version later.</para></listitem>
 
-<listitem><para><userinput>--sysconfdir=/etc</userinput>: This option
-tells the binaries created by the package to look in /etc for their
-configuration files</para></listitem>
-
 <listitem><para><userinput>--disable-whois</userinput>: This option disables
 the building of the inetutils whois client, which is woefully out of date.
 Instructions for a better whois client are in the BLFS book.</para></listitem>

chapter06/less-inst.xml

@@ -7,6 +7,14 @@
 
 <para><screen><userinput>./configure --prefix=/usr --bindir=/bin --sysconfdir=/etc</userinput></screen></para>
 
+<para>The meaning of the configure option:</para>
+
+<itemizedlist>
+<listitem><para><userinput>--sysconfdir=/etc</userinput>: This option tells the
+programs created by the package to look in <filename>/etc</filename> for their
+configuration files.</para></listitem>
+</itemizedlist>
+
 <para>Compile the package:</para>
 
 <para><screen><userinput>make</userinput></screen></para>

chapter06/psmisc-inst.xml

@@ -7,7 +7,7 @@
 
 <para><screen><userinput>./configure --prefix=/usr --exec-prefix=/</userinput></screen></para>
 
-<para>The meaning of the new configure option:</para>
+<para>The meaning of the configure option:</para>
 
 <itemizedlist>
 <listitem><para><userinput>--exec-prefix=/</userinput>: This causes the