Shifting chapter contents, and moving preparational sections of chapter 5 to a separate chapter.

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

4 files changed, 146 insertions, 47 deletions

diff --git a/chapter01/askforhelp.xml b/chapter01/askforhelp.xml
new file mode 100644
index 000000000..c4f3fa47f
--- /dev/null
+++ b/chapter01/askforhelp.xml
@@ -0,0 +1,103 @@
+<sect1 id="prepare-askforhelp">
+<title>How to ask for help</title>
+<?dbhtml filename="askforhelp.html" dir="chapter02"?>
+
+<para>If you encounter a problem while using this book, and your problem
+is not listed in the FAQ (<ulink url="&faq-root;"/>), you will find that
+most of the people on Internet Relay Chat (IRC) and on the mailing lists
+are willing to help you (see <xref linkend="ch-scatter-administrativa"/>.
+To assist us in diagnosing and solving your problem, include as much relevant
+information as possible in your request for help.</para>
+
+<sect2>
+<title>Things to mention</title>
+ 
+<para>Apart from a brief explanation of the problem you're having, the
+essential things to include in your request are:</para>
+
+<itemizedlist>
+<listitem><para>the version of the book you are using (being &version;),</para></listitem>
+<listitem><para>the host distribution and version you are using to create
+LFS from,</para></listitem>
+<listitem><para>the package or section giving you problems,</para></listitem>
+<listitem><para>the exact error message or symptom you are receiving,</para></listitem>
+<listitem><para>whether you have deviated from the book at all.</para></listitem>
+</itemizedlist>
+
+<para>(Note that saying that you've deviated from the book doesn't mean
+that we won't help you. After all, LFS is about choice. It'll just
+help us to see other possible causes of your problem.)</para>
+
+</sect2>
+
+<sect2>
+<title>Configure problems</title>
+
+<para>When something goes wrong during the stage where the configure script
+is run, look through the <filename>config.log</filename> file. This file
+may contain errors encountered during configure which weren't printed to
+the screen. Include those relevant lines if you decide to ask for
+help.</para>
+
+</sect2>
+
+<sect2>
+<title>Compile problems</title>
+
+<para>To help us find the cause of the problem, both screen output and
+the contents of various files are useful. The screen output from both
+the ./configure script and the make run can be useful. Don't blindly
+include the whole thing but on the other hand, don't include too little.
+As an example, here is some screen output from make:</para>
+
+<screen>gcc -DALIASPATH=\"/mnt/lfs/usr/share/locale:.\"
+-DLOCALEDIR=\"/mnt/lfs/usr/share/locale\" -DLIBDIR=\"/mnt/lfs/usr/lib\"
+-DINCLUDEDIR=\"/mnt/lfs/usr/include\" -DHAVE_CONFIG_H -I. -I.
+-g -O2 -c getopt1.c
+gcc -g -O2 -static -o make ar.o arscan.o commands.o dir.o expand.o file.o
+function.o getopt.o implicit.o job.o main.o misc.o read.o remake.o rule.o
+signame.o variable.o vpath.o default.o remote-stub.o version.o opt1.o
+-lutil job.o: In function `load_too_high':
+/lfs/tmp/make-3.79.1/job.c:1565: undefined reference to `getloadavg'
+collect2: ld returned 1 exit status
+make[2]: *** [make] Error 1
+make[2]: Leaving directory `/lfs/tmp/make-3.79.1'
+make[1]: *** [all-recursive] Error 1
+make[1]: Leaving directory `/lfs/tmp/make-3.79.1'
+make: *** [all-recursive-am] Error 2</screen>
+
+<para>In this case, many people just include the bottom section where it
+says:</para>
+
+<screen>make [2]: *** [make] Error 1</screen>
+
+<para>and onwards. This isn't enough for us to diagnose the problem because it
+only tells us that <emphasis>something</emphasis> went wrong, not
+<emphasis>what</emphasis> went wrong. The whole section, as in the example
+above, is what should be included to be helpful, because it includes the
+command that was executed and the command's error message(s).</para>
+
+<para>An excellent article on asking for help on the Internet in general
+has been written by Eric S. Raymond. It is available online at <ulink
+url="http://catb.org/~esr/faqs/smart-questions.html"/>.
+Read and follow the hints in that document and you are much more likely
+to get a response to start with and also to get the help you actually
+need.</para>
+
+</sect2>
+
+<sect2>
+<title>Test suite problems</title>
+
+<para>Many packages provide a test suite which, depending on the importance
+of the package, we may encourage you to run. Sometimes packages will
+generate false or expected failures. If you encounter these, you can check
+the LFS Wiki page at <ulink url="&wiki-root;"/> to see whether we have
+already noted and investigated them. If we already know
+about them, then usually there is no need to be concerned.</para>
+
+</sect2>
+
+
+</sect1>
+
diff --git a/chapter01/chapter01.xml b/chapter01/chapter01.xml
index 20020fa3b..0782d3e5c 100644
--- a/chapter01/chapter01.xml
+++ b/chapter01/chapter01.xml
@@ -5,5 +5,6 @@
 &c1-how;
 &c1-changelog;
 &c1-resources;
+&c1-askforhelp;
 
 </chapter>
diff --git a/chapter01/contactinfo.xml b/chapter01/contactinfo.xml
index d88eadb63..0d8351e43 100644
--- a/chapter01/contactinfo.xml
+++ b/chapter01/contactinfo.xml
@@ -27,7 +27,7 @@ support channel is named #LFS-support.</para>
 </sect2>
 
 
-<sect2 id="ch-scatter-maillists" xreflabel="Chapter 1 - Mailing lists">
+<sect2 id="ch-scatter-maillists">
 <title>Mailing lists</title>
 
 <para>The <emphasis>linuxfromscratch.org</emphasis> server is hosting a number
diff --git a/chapter01/how.xml b/chapter01/how.xml
index c5fb2f96b..18bbfc3fc 100644
--- a/chapter01/how.xml
+++ b/chapter01/how.xml
@@ -9,62 +9,57 @@ programs like a compiler, linker and shell to build the new system. Normally
 all the required tools are available if you selected <quote>development</quote>
 as one of the options when you installed your distribution.</para>
 
-<para>In <xref linkend="chapter-making-space"/> you will first create a new Linux native
+<para>In <xref linkend="chapter-making-space"/> you will first create a new
 partition and file system, the place where your new LFS system will be compiled
-and installed. Then in <xref linkend="chapter-getting-materials"/> you download all the
-packages and patches required to build an LFS system, and store them on the new
-file system.</para>
+and installed. Then in <xref linkend="chapter-getting-materials"/> you download
+all the packages and patches needed to build an LFS system, and store them on
+the new file system. In <xref linkend="chapter-preparation"/> you set up a good
+environment to work in.</para>
 
-<para><xref linkend="chapter-temporary-tools"/> then discusses the installation of a number
-of packages that will form the basic development suite (or toolchain) which is
-used to build the actual system in <xref linkend="chapter-building-system"/>. Some of these
-packages are needed to resolve circular dependencies -- for example, to compile
-a compiler you need a compiler.</para>
+<para><xref linkend="chapter-temporary-tools"/> then discusses the installation
+of a number of packages that form the basic development suite used to build the
+actual system in <xref linkend="chapter-building-system"/>.</para>
 
-<para>The first thing to be done in <xref linkend="chapter-temporary-tools"/> is build a
-first pass of the toolchain, made up of Binutils and GCC. The programs from
-these packages will be linked statically in order for them to be usable
-independently of the host system. The second thing to do is build Glibc, the
-C library. Glibc will be compiled by the toolchain programs we just built in
-the first pass. The third thing to do is build a second pass of the toolchain.
-This time the toolchain will be dynamically linked against the newly built
-Glibc. The remaining <xref linkend="chapter-temporary-tools"/> packages are all built using
-this second pass toolchain and dynamically linked against the new
-host-independent Glibc. When this is done, the LFS installation process will no
-longer depend on the host distribution, with the exception of the running
-kernel.</para>
+<para>The first thing to be done in <xref linkend="chapter-temporary-tools"/>
+is build a first pass of the <emphasis>toolchain</emphasis>, consisting of
+Binutils and GCC. The programs from these packages will be linked statically in
+order for them to be usable independently of the host system (thus making it
+in theory possible to skip the second passes). The second thing to do is build
+Glibc, the C library. Glibc will be compiled by the just-built toolchain
+programs. The third thing to do is build a second pass of the toolchain, this
+time linking it dynamically against the newly built Glibc. The remaining <xref
+linkend="chapter-temporary-tools"/> packages are all built using this second
+pass toolchain and are dynamically linked against the new host-independent
+Glibc. When this is done, the LFS installation process will no longer depend on
+the host distribution, with the exception of the running kernel.</para>
 
 <para>You may be thinking that <quote>this seems like a lot of work, just to
 get away from my host distribution</quote>. Well, a full technical explanation
-is provided at the start of <xref linkend="chapter-temporary-tools"/>, including some notes
-on the differences between statically and dynamically linked programs.</para>
+is provided at the start of <xref linkend="chapter-temporary-tools"/>,
+including some notes on the differences between statically and dynamically
+linked programs.</para>
 
-<para>In <xref linkend="chapter-building-system"/> your real LFS system will be built. The
-chroot (change root) program is used to enter a virtual environment and start
-a new shell whose root directory will be set to the LFS partition. This is very
-similar to rebooting and instructing the kernel to mount the LFS partition as
-the root partition. The reason that you don't actually reboot, but instead
-chroot, is that creating a bootable system requires additional work which isn't
-necessary just yet. But the major advantage is that chrooting allows you to
-continue using the host while LFS is being built. While waiting for package
-compilation to complete, you can simply switch to a different VC (Virtual
-Console) or X desktop and continue using the computer as you normally
-would.</para>
+<para>In <xref linkend="chapter-building-system"/> your real LFS system will be
+built. The <command>chroot</command> (change root) program is used to enter a
+virtual environment and start a new shell whose root directory will be set to
+the LFS partition. This is very similar to rebooting and instructing the kernel
+to mount the LFS partition as the root partition. The reason that you don't
+actually reboot, but instead chroot, is that creating a bootable system
+requires additional work which isn't necessary just yet. But the major
+advantage is that chrooting allows you to continue using the host while LFS is
+being built. While waiting for package compilation to complete, you can simply
+switch to a different VC (Virtual Console) or X desktop and continue using the
+computer as you normally would.</para>
 
 <para>To finish the installation, the bootscripts are set up in
 <xref linkend="chapter-bootscripts"/>, the kernel and bootloader are set up in
-<xref linkend="chapter-mixture"/>, and <xref linkend="chapter-finalizing"/> contains some
-pointers to help you after you finish the book. Then, finally, you're ready to
-reboot your computer into your new LFS system.</para>
+<xref linkend="chapter-mixture"/>, and <xref linkend="chapter-finalizing"/>
+contains some pointers to help you after you finish the book. Then, finally,
+you're ready to reboot your computer into your new LFS system.</para>
 
-<para>This is the process in a nutshell. Detailed information on the steps you 
-will take are discussed in the chapters and package descriptions as you 
-progress through them. If something isn't completely clear now, don't worry, 
-everything will fall into place soon.</para>
-
-<para>Please read <xref linkend="chapter-preparation"/> carefully as it explains a few
-important things you should be aware of before you begin to work through
-<xref linkend="chapter-temporary-tools"/> and beyond.</para>
+<para>This is the process in a nutshell. Detailed information on all the steps
+taken is given in the chapters and sections as you progress through them. If
+something isn't completely clear now, don't worry, everything will fall into
+place soon.</para>
 
 </sect1>
-