Tighten up this sub-section and format as an itemized list.

Sponsored by: iXsystems

1 files changed, 94 insertions, 166 deletions

diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
index 9c2c604b53..c8ef3f0698 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -2441,18 +2441,16 @@ Script done, &hellip;</screen>
     </sect2>
 
     <sect2 xml:id="updating-questions">
-      <title>Questions</title>
-
-      <qandaset>
-	<qandaentry>
-	  <question>
-	    <para>Do I need to re-make the world for every
-	      change?</para>
-	  </question>
-
-	  <answer>
-	    <para>There is no easy answer, as it depends on the nature
-	      of the change.  For example, if running
+      <title>Common Questions</title>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Do I need to re-make the world for every
+	      change?</term>
+
+	  <listitem>
+	    <para>It depends upon the nature
+	      of the change.  For example, if
 	      <application>svn</application> only shows the following
 	      files as being updated:</para>
 
@@ -2465,108 +2463,77 @@ Script done, &hellip;</screen>
 	    <para>it probably is not worth rebuilding the entire
 	      world.  Instead, go into the appropriate sub-directories
 	      and run <command>make all install</command>.  But if
-	      something major changed, such as
-	      <filename>src/lib/libc/stdlib</filename>, either
-	      re-make world, or at least those parts of it that are
-	      statically linked.</para>
+	      something major changes, such as
+	      <filename>src/lib/libc/stdlib</filename>, consider
+	      rebuilding world.</para>
 
-	    <para>At the end of the day, it is your call.  Some users
-	      re-make the world every fortnight and let changes
+	    <para>Some users
+	      rebuild world every fortnight and let changes
 	      accumulate over that fortnight.  Others only re-make
 	      those things that have changed and are careful to spot
-	      all the dependencies.</para>
-
-	    <para>It all depends on how often a user wants to upgrade
+	      all the dependencies.  It all depends on how often a user wants to upgrade
 	      and whether they are tracking &os.stable; or
 	      &os.current;.</para>
-	  </answer>
-	</qandaentry>
+	  </listitem>
+	</varlistentry>
 
-	<qandaentry>
-	  <question>
-	    <para>My compile failed with lots of
+	<varlistentry>
+	    <term>What would cause a compile to fail with lots of
 	      signal 11<indexterm>
 		<primary>signal 11</primary>
 	      </indexterm>
-	      (or other signal number) errors.  What happened?</para>
-	  </question>
+	      (or other signal number) errors?</term>
 
-	  <answer>
-	    <para>This normally indicates hardware problems.
-	      (Re)making world is an effective way to stress test
-	      hardware, and will frequently throw up memory
-	      problems which normally manifest themselves as the
-	      compiler mysteriously aborts.</para>
-
-	    <para>A sure indicator of this occurs when
+	  <listitem>
+	    <para>This normally indicates a hardware problem.
+	      Building world is an effective way to stress test
+	      hardware, especially memory.  A sure indicator of a hardware issue is when
 	      <application>make</application> is restarted and it
 	      dies at a different point in the process.</para>
 
-	    <para>To resolve this error, start swapping around the
-	      components in the machine to determine which one is
+	    <para>To resolve this error, swap out the
+	      components in the machine, starting with RAM, to determine which component is
 	      failing.</para>
-	  </answer>
-	</qandaentry>
+	  </listitem>
+	</varlistentry>
 
-	<qandaentry>
-	  <question>
-	    <para>Can <filename>/usr/obj</filename>
-	      be removed when finished?</para>
-	  </question>
+	<varlistentry>
+	    <term>Can <filename class="directory">/usr/obj</filename>
+	      be removed when finished?</term>
 
-	  <answer>
-	    <para>The short answer is yes.</para>
+	  <listitem>
 
-	    <para><filename>/usr/obj</filename>
+	    <para>This directory
 	      contains all the object files that were produced during
 	      the compilation phase.  Normally, one of the first steps
 	      in the <command>make buildworld</command> process is to
 	      remove this directory and start afresh.  Keeping
 	      <filename>/usr/obj</filename> around
 	      when finished makes little sense, and its removal frees
-	      up a approximately 2&nbsp;GB of disk space.</para>
-
-	    <para>Advances users can instruct
-	      <command>make buildworld</command> to skip this step.
-	      This speeds up subsequent builds, since most of the
-	      sources will not need to be recompiled.  The flip side
-	      is that subtle dependency problems can creep in, causing
-	      the build to fail in odd ways.  This frequently
-	      generates noise on the &os; mailing lists, when one
-	      person complains that their build has failed, not
-	      realizing that it is because they have tried to cut
-	      corners.</para>
-	  </answer>
-	</qandaentry>
-
-	<qandaentry>
-	  <question>
-	    <para>Can interrupted builds be resumed?</para>
-	  </question>
-
-	  <answer>
-	    <para>This depends on how far into the process the
-	      problem occurs.</para>
+	      up a approximately 2GB of disk space.</para>
+	  </listitem>
+	</varlistentry>
 
-	    <para>In general, <command>make buildworld</command>
-	      builds new copies of essential tools, such as
-	      &man.gcc.1; and &man.make.1;, and the system libraries.
+	<varlistentry>
+	    <term>Can interrupted builds be resumed?</term>
+
+	  <listitem>
+	    <para>This depends on how far into the process the
+	      problem occurs.  In general, <command>make buildworld</command>
+	      builds new copies of essential tools and the system libraries.
 	      These tools and libraries are then installed, used to
-	      rebuild themselves, and are installed again.  The entire
-	      system, including regular user programs such as
-	      &man.ls.1; or &man.grep.1;, is then rebuilt with the new
-	      system files.</para>
+	      rebuild themselves, and are installed again.  The rest of the
+	      system is then rebuilt with the new
+	      system tools.</para>
 
-	    <para>During the last stage, it is fairly safe to:</para>
+	    <para>During the last stage, it is fairly safe to run
+	      these commands as they will not undo the work of the previous
+	      <command>make buildworld</command>:</para>
 
-	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
-&prompt.root; <userinput>cd /usr/src</userinput>
+	    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
 
-	    <para>This will not undo the work of the previous
-	      <command>make buildworld</command>.</para>
-
-	    <para>If you see the message:</para>
+	    <para>If this message appears:</para>
 
 	    <screen>--------------------------------------------------------------
 Building everything..
@@ -2575,72 +2542,36 @@ Building everything..
 	    <para>in the <command>make buildworld</command> output,
 	      it is probably fairly safe to do so.</para>
 
-	    <para>If that message is not displayed, or you are not
-	      sure, it is always better to be safe than sorry, and
+	    <para>If that message is not displayed,
+	      it is always better to be safe than sorry and to
 	      restart the build from scratch.</para>
-	  </answer>
-	</qandaentry>
-
-	<qandaentry>
-	  <question>
-	    <para>How can I speed up making the world?</para>
-	  </question>
-
-	  <answer>
-	    <itemizedlist>
-	      <listitem>
-		<para>Run it in single user mode.</para>
-	      </listitem>
-
-	      <listitem>
-		<para>Put <filename>/usr/src</filename> and
-		  <filename>/usr/obj</filename>
-		  on separate file systems held on separate disks.  If
-		  possible, put these disks on separate disk
-		  controllers.</para>
-	      </listitem>
-
-	      <listitem>
-		<para>Alternately, put these file systems across
-		  multiple disks using &man.ccd.4;.</para>
-	      </listitem>
-
-	      <listitem>
-		<para>Turn off profiling by setting
-		  <quote>NO_PROFILE=true</quote> in
-		  <filename>/etc/make.conf</filename>.</para>
-	      </listitem>
-
-	      <listitem>
-		<para>Pass
-		  <option>-j<replaceable>n</replaceable></option>
-		  to &man.make.1; to run multiple processes in
-		  parallel.  This usually helps on both single and
-		  multi processor machines.</para>
-	      </listitem>
-
-	      <listitem>
-		<para>The file system holding
-		  <filename>/usr/src</filename> can
-		  be mounted or remounted with
-		  <option>noatime</option>.
-		  This prevents the file system from recording the
-		  file access time which is probably not
-		  needed.</para>
-
-		<screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
+	  </listitem>
+	</varlistentry>
 
-		<warning>
-		  <para>This example assumes
-		    <filename>/usr/src</filename> is on its own file
-		    system.  If it is part of
-		    <filename>/usr</filename>, then use that file
-		    system mount point instead.</para>
-		</warning>
-	      </listitem>
+	<varlistentry>
+	    <term>Is it possible to speed up making the world?</term>
 
-	      <listitem>
-		<para>The file system holding
+	  <listitem>
+		<para>Several actions can speed up the build world
+		  process.  For example, the entire process can be run from
+		  single-user mode.  However, this will prevent users
+		  from having access
+		  to the system until the process is complete.</para>
+
+		<para>Careful file system design or the use of ZFS
+		  datasets can make a difference.  Consider putting <filename class="directory">/usr/src</filename> and
+		  <filename class="directory">/usr/obj</filename>
+		  on separate file systems.  If possible, place the file systems on separate disks on separate disk
+		  controllers.  When mounting
+		  <filename class="directory">/usr/src</filename>, use
+		  <option>noatime</option> which
+		  prevents the file system from recording the
+		  file access time.  If <filename
+		  class="directory">/usr/src</filename> is not on its
+		  own file system, consider remounting <filename
+		  class="directory">/usr</filename> with <option>noatime</option>.</para>
+
+		  <para>The file system holding
 		  <filename>/usr/obj</filename> can be mounted or
 		  remounted with <option>async</option> so that disk
 		  writes happen asynchronously.  The write completes
@@ -2663,25 +2594,22 @@ Building everything..
 		    backups before enabling this option.</para>
 		</warning>
 
-		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
+		<para>Turn off profiling by setting
+		  <quote>NO_PROFILE=true</quote> in
+		  <filename>/etc/make.conf</filename>.</para>
 
-		<warning>
-		  <para>If <filename>/usr/obj</filename> is
-		    not on its own file system, replace it in the
-		    example with the name of the appropriate mount
-		    point.</para>
-		</warning>
+		<para>Pass
+		  <option>-j<replaceable>n</replaceable></option>
+		  to &man.make.1; to run multiple processes in
+		  parallel.  This usually helps on both single- and
+		  multi-processor machines.</para>
 	      </listitem>
-	    </itemizedlist>
-	  </answer>
-	</qandaentry>
+	</varlistentry>
 
-	<qandaentry>
-	  <question>
-	    <para>What do I do if something goes wrong?</para>
-	  </question>
+	<varlistentry>
+	    <term>What do I do if something goes wrong?</term>
 
-	  <answer>
+	  <listitem>
 	    <para>Make absolutely sure that the environment has no
 	      extraneous cruft from earlier builds:</para>
 
@@ -2701,9 +2629,9 @@ Building everything..
 	      output of <command>uname -a</command> to &a.questions;.
 	      Be prepared to answer other questions about the
 	      setup!</para>
-	  </answer>
-	</qandaentry>
-      </qandaset>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
     </sect2>
   </sect1>