Making the test suites in chapter 5 more clearly optional.

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

17 files changed, 83 insertions, 137 deletions

diff --git a/appendixa/expect-shortdesc.xml b/appendixa/expect-shortdesc.xml
index 7710293c4..8915cf2ca 100644
--- a/appendixa/expect-shortdesc.xml
+++ b/appendixa/expect-shortdesc.xml
@@ -4,7 +4,7 @@
 
 <para><emphasis>Installed program</emphasis>: expect</para>
 
-<para><emphasis>Installed library</emphasis>: libexpect5.39.a</para>
+<para><emphasis>Installed library</emphasis>: libexpect&expect-version;.a</para>
 
 </sect2>
 
diff --git a/chapter02/abouttestsuites.xml b/chapter02/abouttestsuites.xml
index e580a9a79..ccf6c8099 100644
--- a/chapter02/abouttestsuites.xml
+++ b/chapter02/abouttestsuites.xml
@@ -5,37 +5,36 @@
 <para>Most packages provide a test suite. Running the test suite for a newly
 built package is generally a good idea, as it can provide a nice sanity check
 that everything compiled correctly. A test suite that passes its set of checks
-usually proves that the package is functioning mostly as the developer
-intended. It does not, however, guarantee that the package is totally bug
-free.</para>
+usually proves that the package is functioning as the developer intended. It
+does not, however, guarantee that the package is totally bug free.</para>
 
 <para>Some test suites are more important than others. For example, the test
-suites for the core toolchain packages -- GCC, Binutils, and Glibc (the C
-library) -- are of the utmost importance due to their central role in a
-properly functioning system. But be warned, the test suites for GCC and Glibc
-can take a very long time to complete, especially on slower hardware.</para>
+suites for the core toolchain packages -- GCC, Binutils, and Glibc -- are of
+the utmost importance due to their central role in a properly functioning
+system. But be warned, the test suites for GCC and Glibc can take a very long
+time to complete, especially on slower hardware.</para>
 
-<para>Experience has shown us that there is little to be gained from running
-the test suites in <xref linkend="chapter-temporary-tools"/>. There can be no escaping the
-fact that the host system always exerts influence on the tests in that chapter,
-often causing weird and inexplicable failures. Not only that, the tools built
-in <xref linkend="chapter-temporary-tools"/> are temporary and eventually discarded. For the
-average reader of this book we recommend <emphasis>not</emphasis> to run the
-test suites in <xref linkend="chapter-temporary-tools"/>. The instructions for running those
-test suites are still provided for the benefit of testers and developers, but
-they are strictly optional for everyone else.</para>
+<note><para>Experience has shown us that there is little to be gained from running
+the test suites in <xref linkend="chapter-temporary-tools"/>. There can be no
+escaping the fact that the host system always exerts some influence on the
+tests in that chapter, often causing weird and inexplicable failures. Not only
+that, the tools built in <xref linkend="chapter-temporary-tools"/> are
+temporary and eventually discarded. For the average reader of this book we
+recommend <emphasis>not</emphasis> to run the test suites in <xref
+linkend="chapter-temporary-tools"/>. The instructions for running those test
+suites are still provided for the benefit of testers and developers, but they
+are strictly optional for everyone else.</para></note>
 
-<para>As you progress through the book and encounter the commands to run the
-various test suites, we'll guide you on the relative importance of the test
-suite in question, so that you can decide for yourself whether to run that one
-or not.</para>
-
-<note><para>A common problem when running the test suites for Binutils and GCC
-is running out of pseudo terminals (PTYs for short). The symptom is an
-unusually high number of failing tests. This can happen for a number of
-reasons. Most likely is that the host system doesn't have the
+<para>A common problem when running the test suites for Binutils and GCC is
+running out of pseudo terminals (PTYs for short). The symptom is a very high
+number of failing tests. This can happen for several reasons, but the most
+likely cause is that the host system doesn't have the
 <emphasis>devpts</emphasis> file system set up correctly. We'll discuss this in
-more detail later on in <xref linkend="chapter-temporary-tools"/>.</para></note>
+more detail later on in <xref linkend="chapter-temporary-tools"/>.</para>
+
+<para>Sometimes package test suites will give false failures. You can
+consult the LFS Wiki at <ulink url="&wiki-root;"/> to verify that these
+failures are normal. This applies to all tests throughout the book.</para>
 
 </sect1>
 
diff --git a/chapter04/chapter04.xml b/chapter04/chapter04.xml
index 038038944..d050c8bcf 100644
--- a/chapter04/chapter04.xml
+++ b/chapter04/chapter04.xml
@@ -167,7 +167,7 @@ M4 (&m4-version;) - &m4-size;:
 <ulink url="http://freshmeat.net/projects/gnum4/"/>
 
 Make (&make-version;) - &make-size;:
-<ulink url="http://freshmeat.net/projects/gnumake"/>
+<ulink url="http://freshmeat.net/projects/gnumake/"/>
 
 Make_devices (&makedev-version;) - &makedev-size;:
 <ulink url="&lfs-root;~alex/make_devices-&makedev-version;.bz2"/>
diff --git a/chapter05/bash.xml b/chapter05/bash.xml
index 05e62ab97..45e12e64e 100644
--- a/chapter05/bash.xml
+++ b/chapter05/bash.xml
@@ -26,11 +26,8 @@ patch:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Bash test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make tests</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make tests</userinput>.)</para>
 
 <para>Then install it and its documentation:</para>
 
diff --git a/chapter05/coreutils.xml b/chapter05/coreutils.xml
index cea1f6fd6..6672e18d5 100644
--- a/chapter05/coreutils.xml
+++ b/chapter05/coreutils.xml
@@ -18,14 +18,15 @@ And for the patch:
 <title>Installation of Coreutils</title>
 
 <para>Coreutils has an issue when compiled against Glibc-&glibc-version;.
-Without the patch below, some of the Coreutils utilities (head, tail, sort etc)
-will reject their traditional syntax which has been in use for approximately 30
-years. The old syntax is so pervasive that compatibility must be preserved until
-the many places where it is used can be updated. More details are provided in
-the comments inside the patch itself. Use of this patch is by no means
-compulsory but opting not to use it means you'll have deal with the consequences
-yourself, i.e. patch the many software packages that use the old syntax. Apply
-the patch:</para>
+Without the patch below, some of the Coreutils utilities
+(<command>head</command>, <command>tail</command>, <command>sort</command>,
+and others) will reject their traditional syntax which 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.
+More details on this are provided in the comments inside the patch itself. Use
+of this patch is by no means compulsory, but not using it means you'll have to
+deal with the consequences yourself: patch the many packages that use the old
+syntax. Therefore, better apply the patch:</para>
 
 <screen><userinput>patch -Np1 -i ../&coreutils-posixver-patch;</userinput></screen>
 
@@ -37,20 +38,11 @@ the patch:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Coreutils
-test suite anyway, the following command will do so:</para>
-
-<screen><userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput></screen>
-
-<para>The meaning of the make parameter:</para>
-
-<itemizedlist>
-<listitem><para><userinput>RUN_EXPENSIVE_TESTS=yes</userinput>: This tells the
-test suite to run several additional tests that are considered relatively
-expensive on some platforms. However, they are generally not a problem on
-Linux.</para></listitem>
-</itemizedlist>
+<para>(If you insist on testing the results, then issue:
+<userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput>. The
+<emphasis>RUN_EXPENSIVE_TESTS=yes</emphasis> parameter tells the test suite to
+run several additional tests that are considered relatively expensive on some
+platforms but generally are not a problem on Linux.)</para>
 
 <para>And install the package:</para>
 
diff --git a/chapter05/expect.xml b/chapter05/expect.xml
index 3720ecbcc..5cdcba409 100644
--- a/chapter05/expect.xml
+++ b/chapter05/expect.xml
@@ -44,16 +44,13 @@ libraries, both of which may possibly reside on the host system.</para></listite
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Expect test
-suite anyway, the following command will do so. However, you should be aware
-that the Expect test suite is sometimes known to experience failures under
-certain host conditions that are not fully understood. Therefore, test suite
-failures here are not surprising, but are not considered critical:</para>
+<para>(If you insist on testing the results, then issue:
+<userinput>make test</userinput>. However, the Expect 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.)</para>
 
-<screen><userinput>make test</userinput></screen>
-
-<para>And install:</para>
+<para>And install it:</para>
 
 <screen><userinput>make SCRIPTS="" install</userinput></screen>
 
diff --git a/chapter05/findutils.xml b/chapter05/findutils.xml
index f31929aea..8d76082e7 100644
--- a/chapter05/findutils.xml
+++ b/chapter05/findutils.xml
@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Findutils
-test suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>And install the package:</para>
 
diff --git a/chapter05/gawk.xml b/chapter05/gawk.xml
index 7bf1d1314..62c84523b 100644
--- a/chapter05/gawk.xml
+++ b/chapter05/gawk.xml
@@ -23,11 +23,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Gawk test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>And install it:</para>
 
diff --git a/chapter05/gettext.xml b/chapter05/gettext.xml
index a8eda134e..9e3ca36aa 100644
--- a/chapter05/gettext.xml
+++ b/chapter05/gettext.xml
@@ -21,16 +21,12 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Gettext test
-suite anyway, the following command will do so. However, you should be aware
-that the Gettext test suite is known to experience failures under certain host
-conditions -- for example, when it finds a Java compiler on the host (Note: an
-experimental patch to disable Java is available from the patches project). Not
-only that, the Gettext test suite takes an excessive amount of time to run and
-is not considered critical:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue: <userinput>make
+check</userinput>. This takes a very long time, around 6 SBUs. Moreover, the
+Gettext test suite is known to experience failures under certain host
+conditions -- for example when it finds a Java compiler on the host (but an
+experimental patch to disable Java is available from the LFS Patches
+project).)</para>
 
 <para>And install the package:</para>
 
diff --git a/chapter05/grep.xml b/chapter05/grep.xml
index e05a15341..c40e7ed84 100644
--- a/chapter05/grep.xml
+++ b/chapter05/grep.xml
@@ -34,11 +34,8 @@ use the code from Glibc, which is known to be slightly buggy.</para></listitem>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Grep test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>Then install them and their documentation:</para>
 
diff --git a/chapter05/kernelheaders.xml b/chapter05/kernelheaders.xml
index 67636e622..ba3b2720a 100644
--- a/chapter05/kernelheaders.xml
+++ b/chapter05/kernelheaders.xml
@@ -38,7 +38,7 @@ symlink:</para>
 cp include/asm/* /tools/include/asm
 cp -R include/asm-generic /tools/include</userinput></screen>
 
-<para>Install the cross-platform kernel header files:</para>
+<para>And finally install the cross-platform kernel header files:</para>
 
 <screen><userinput>cp -R include/linux /tools/include</userinput></screen>
 
diff --git a/chapter05/make.xml b/chapter05/make.xml
index d182385a6..fb34e27b1 100644
--- a/chapter05/make.xml
+++ b/chapter05/make.xml
@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Make test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>Then install it and its documentation:</para>
 
diff --git a/chapter05/patch.xml b/chapter05/patch.xml
index ab72274aa..d927b0327 100644
--- a/chapter05/patch.xml
+++ b/chapter05/patch.xml
@@ -13,13 +13,12 @@
 <sect2>
 <title>Installation of Patch</title>
 
-<para>Prepare Patch for compilation:</para>
+<para>Prepare Patch for compilation (the preprocessor flag
+<emphasis>-D_GNU_SOURCE</emphasis> is only needed on the PowerPC platform, on
+other architectures you can leave it out):</para>
 
 <screen><userinput>CPPFLAGS=-D_GNU_SOURCE ./configure --prefix=/tools</userinput></screen>
 
-<para>The preprocessor flag <emphasis>-D_GNU_SOURCE</emphasis> is only needed
-on the PowerPC platform. On other architectures you can leave it out.</para>
-
 <para>Compile the program:</para>
 
 <screen><userinput>make</userinput></screen>
diff --git a/chapter05/sed.xml b/chapter05/sed.xml
index 1d6b81870..0102760da 100644
--- a/chapter05/sed.xml
+++ b/chapter05/sed.xml
@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Sed test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>Then install it and its documentation:</para>
 
diff --git a/chapter05/tar.xml b/chapter05/tar.xml
index 54404d197..384a73d06 100644
--- a/chapter05/tar.xml
+++ b/chapter05/tar.xml
@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Tar test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>Then install them and their documentation:</para>
 
diff --git a/chapter05/tcl.xml b/chapter05/tcl.xml
index 1668a895d..4d51cb53c 100644
--- a/chapter05/tcl.xml
+++ b/chapter05/tcl.xml
@@ -32,28 +32,15 @@ chapter.</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Tcl test
-suite anyway, the following command will do so. However, you should be aware
-that the Tcl test suite is sometimes known to experience failures under certain
-host conditions that are not fully understood. Therefore, test suite failures
-here are not surprising, but are not considered critical:</para>
-
-<screen><userinput>TZ=UTC make test</userinput></screen>
-
-<para>The meaning of the make parameter:</para>
-
-<itemizedlist>
-<listitem><para><userinput>TZ=UTC</userinput>: This 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 the clock tests are
-exercised correctly. More information on the TZ environment variable will be
-given later on in <xref linkend="chapter-bootscripts"/>.</para></listitem>
-</itemizedlist>
-
-<para>Sometimes package test suites will give false failures. You can
-consult the LFS Wiki at <ulink url="&wiki-root;"/> to verify that these
-failures are normal. This applies to all tests throughout the book.</para>
+<para>(If you insist on testing the results, then issue:
+<userinput>TZ=UTC make test</userinput>. However, 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 <emphasis>TZ=UTC</emphasis> 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 the clock
+tests are exercised correctly. More information on the TZ environment variable
+will be given later on in <xref linkend="chapter-bootscripts"/>.)</para>
 
 <para>Install the package:</para>
 
@@ -69,7 +56,7 @@ will need its internal headers.</para></warning>
 <!-- HACK - Force some whitespace to appease tidy -->
 <literallayout></literallayout>
 
-<para>Make a necessary symbolic link:</para>
+<para>And make a necessary symbolic link:</para>
 
 <screen><userinput>ln -s tclsh8.4 /tools/bin/tclsh</userinput></screen>
 
diff --git a/chapter05/texinfo.xml b/chapter05/texinfo.xml
index fad95fb7f..eee6e2a55 100644
--- a/chapter05/texinfo.xml
+++ b/chapter05/texinfo.xml
@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
-temporary tools here in this chapter. If you still want to run the Texinfo test
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
+<para>(If you insist on testing the results, then issue:
+<userinput>make check</userinput>.)</para>
 
 <para>Then install them and their documentation:</para>