Initial shuffle in this section, much more to come in order to improve its flow.

Place pre-build tasks at beginning and format as a procedure.

Sponsored by: iXsystems

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

@@ -1437,46 +1437,53 @@ before running "/usr/sbin/freebsd-update install"</screen>
     </indexterm>
     <para>Once the local source tree is synchronized against a
       particular version of &os; such as &os.stable; or &os.current;,
-      the source tree can be used to rebuild the system.</para>
+      the source tree can be used to rebuild the system.  This process
+      is known as rebuilding world.</para>
+      
+    <para><emphasis>Before</emphasis> rebuilding world, be sure to
+      perform the following tasks:</para>
 
-    <warning>
+    <procedure>
-      <title>Make a Backup</title>
+      <title>Perform These Tasks Before Building World</title>
 
-      <para>It cannot be stressed enough how important it is to make a
+      <step>
+	<para>Backup all important data to another system or removable
+	media, verify the integrity of the backup, and have a bootable
+	installation media at hand.  It cannot be
+	stressed enough how important it is to make a
 	backup of the system <emphasis>before</emphasis> rebuilding
-	the system.  While rebuilding the world is an easy task, there
+	the system.  While rebuilding world is an easy task, there
 	will inevitably be times when mistakes in the source tree
-	render the system unbootable.</para>
+	render the system unbootable.  You will probably never have
-
+	to use the backup, but it is better to be safe than sorry!</para>
-      <para>Create and verify a backup and have a bootable
+    </step>
-	installation media at hand.  You will probably never have
-	to use it, but it is better to be safe than sorry!</para>
-    </warning>
-
-    <warning>
-      <title>Subscribe to the Right Mailing List</title>
 
+    <step>
       <indexterm><primary>mailing list</primary></indexterm>
-      <para>The &os.stable; and &os.current; branches are, by their
+      <para>Review the recent &a.stable.name; or &a.current.name; entries, depending
-	nature, <emphasis>in development</emphasis>.  People that
+	upon the branch being tracked.  Be aware of any known
-	contribute to &os; are human, and mistakes occasionally
+	problems and which systems are affected.  If a known issue
-	happen.</para>
+	affects the version of synchronized code, wait for an <quote>all
-
+	  clear</quote> announcement to be posted stating that the problem has
-      <para>Sometimes these mistakes can be quite harmless, just
+	been solved.  Resynchronize the sources to ensure that the
-	causing the system to print a new diagnostic warning.  Or the
+	local version of source has the needed fix.</para>
-	change may be catastrophic, and render the system unbootable
+    </step>
-	or destroy file systems.</para>
+    
-
+    <step>
-      <para>When problems occur, a <quote>heads up</quote> is
+      <para>Read
-	posted to the appropriate mailing list, explaining the nature
+	<filename>/usr/src/UPDATING</filename> for any pre-buildworld
-	of the problem and which systems it affects.  An <quote>all
+	  steps necessary for that version of the source.  This file contains
-	  clear</quote> announcement is posted when the problem has
+	important information about potential problems and may specify
-	been solved.</para>
+	the order to run certain commands.  Many upgrades require
-
+	specific additional steps such as renaming or deleting
-      <para>Users who track &os.stable; or &os.current; and do
+	specific files prior to installworld.  These will be listed
-	not read &a.stable; or &a.current; respectively, are asking
+	at the end of this file where the currently recommended upgrade sequence
-	for trouble.</para>
+	is explicitly spelled out.  If
-    </warning>
+	<filename>UPDATING</filename> contradicts any steps in
+	this chapter, the instructions in <filename>UPDATING</filename> take
+	precedence and should be followed.</para>
+	</step>
+  </procedure>
 
     <warning>
       <title>Do Not Use <command>make world</command></title>
@@ -1492,10 +1499,8 @@ before running "/usr/sbin/freebsd-update install"</screen>
     <sect2 xml:id="canonical-build">
       <title>The Canonical Way to Update Your System</title>
 
-      <para>Before updating the system, read
+      <para>Once the above tasks have been performed,  use
-	<filename>/usr/src/UPDATING</filename> for any pre-buildworld
+	the procedure outlined here to update the system.</para>
-	steps necessary for that version of the sources.  Then, use
-	the procedure outlined here.</para>
 
       <para>These upgrade steps assume an upgrade from an older &os;
 	version, consisting of an old compiler, old kernel,
@@ -1685,13 +1690,6 @@ before running "/usr/sbin/freebsd-update install"</screen>
       <para>When upgrading across major releases, people who do not
 	follow this procedure should expect some problems.</para>
 
-      <para>It is also worth noting that many upgrades may require
-	specific additional steps such as renaming or deleting
-	specific files prior to installworld.  Read
-	<filename>/usr/src/UPDATING</filename> carefully, especially
-	at the end, where the currently recommended upgrade sequence
-	is explicitly spelled out.</para>
-
       <para>This procedure has evolved over time as the developers
 	have found it impossible to completely prevent certain kinds
 	of mismatch problems.  Hopefully, the current procedure will
@@ -1749,25 +1747,6 @@ before running "/usr/sbin/freebsd-update install"</screen>
     </sect2>
 
     <sect2 xml:id="src-updating">
-      <title>Read <filename>/usr/src/UPDATING</filename></title>
-
-      <para>Before updating, read
-	<filename>/usr/src/UPDATING</filename>.  This file contains
-	important information about potential problems and may specify
-	the order to run certain commands.  If
-	<filename>UPDATING</filename> contradicts the procedure in
-	this section, <filename>UPDATING</filename> takes
-	precedence.</para>
-
-      <important>
-	<para>Reading <filename>UPDATING</filename> is not an
-	  acceptable substitute for subscribing to the correct mailing
-	  list.  The two requirements are complementary, not
-	  exclusive.</para>
-      </important>
-    </sect2>
-
-    <sect2 xml:id="make-conf">
       <title>Check <filename>/etc/make.conf</filename></title>
 
       <indexterm>
@@ -1917,12 +1896,9 @@ before running "/usr/sbin/freebsd-update install"</screen>
 &prompt.root; <userinput>rm -rf *</userinput></screen>
     </sect2>
 
-    <sect2 xml:id="updating-upgrading-compilebase">
+    <sect2 xml:id="make-buildworld">
       <title>Recompile the Base System</title>
 
-      <sect3>
-	<title>Saving the Output</title>
-
 	<para>It is a good idea to save the output from running
 	  &man.make.1; to a file.  If something goes wrong, a copy of
 	  the error message can be posted to one of the &os; mailing
@@ -1948,10 +1924,6 @@ Script done, &hellip;</screen>
 	  <filename>/var/tmp</filename> or in
 	  <systemitem class="username">root</systemitem>'s home
 	  directory.</para>
-      </sect3>
-
-      <sect3 xml:id="make-buildworld">
-	<title>Compile the Base System</title>
 
 	<para>While in <filename>/usr/src</filename>
 	  type:</para>
@@ -2068,10 +2040,6 @@ Script done, &hellip;</screen>
 	<para>On a multi-CPU machine using an SMP configured kernel,
 	  try values between 6 and 10 and see how they speed things
 	  up.</para>
-      </sect3>
-
-      <sect3>
-	<title>Timings</title>
 
 	<indexterm>
 	  <primary>rebuilding <quote>world</quote></primary>
@@ -2083,7 +2051,6 @@ Script done, &hellip;</screen>
 	  &os.stable; tree, with no tricks or shortcuts used during
 	  the process.  A &os.current; tree will take somewhat
 	  longer.</para>
-      </sect3>
     </sect2>
 
     <sect2 xml:id="new-kernel">