More shuffling to improve the flow. Still a WIP with much more to come.

Format the build world process as a Procedure.

Sponsored by: iXsystems

1 files changed, 51 insertions, 95 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 8b6ab208cc..e4f2f14ccb 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -1444,7 +1444,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
       perform the following tasks:</para>
 
     <procedure>
-      <title>Perform These Tasks Before Building World</title>
+      <title>Perform These Tasks <emphasis>Before</emphasis> Building World</title>
 
       <step>
 	<para>Backup all important data to another system or removable
@@ -1497,91 +1497,47 @@ before running "/usr/sbin/freebsd-update install"</screen>
     </warning>
 
     <sect2 xml:id="canonical-build">
-      <title>The Canonical Way to Update Your System</title>
-
-      <para>Once the above tasks have been performed,  use
-	the procedure outlined here to update the system.</para>
-
-      <para>These upgrade steps assume an upgrade from an older &os;
-	version, consisting of an old compiler, old kernel,
-	old world, and old configuration files.
-	<quote>World</quote> includes the core system binaries,
-	libraries, and programming files.  The compiler is part of
-	<quote>world</quote>, but has a few special concerns.</para>
-
-      <para>These steps also assume that the sources to a newer
-	version have already been obtained.  If the sources are not
-	up-to-date, refer to <xref linkend="synching"/> for detailed
-	help about synchronizing to a newer version.</para>
-
-      <para>Updating the system from source is a more subtle process
-	than it might initially seem to be, and the &os; developers
-	have found it necessary over the years to change the
-	recommended approach fairly dramatically as new kinds of
-	unavoidable dependencies come to light.  The rest of this
-	section describes the rationale behind the currently
-	recommended upgrade sequence.</para>
-
-      <para>Any successful update sequence must deal with the
-	following issues:</para>
-
-      <itemizedlist>
-	<listitem>
-	  <para>The old compiler might have a bug and not be able to
-	    compile the new kernel.  So, the new kernel should be
-	    built with the new compiler, meaning that the new compiler
-	    must be built before the new kernel is built.  This does
-	    not necessarily mean that the new compiler must be
-	    <emphasis>installed</emphasis> before building the new
-	    kernel.</para>
-	</listitem>
-
-	<listitem>
-	  <para>The new world might rely on new kernel features.  So,
-	    the new kernel must be installed before the new world is
-	    installed.</para>
-	</listitem>
-      </itemizedlist>
-
-      <para>These first two issues are the basis for the
-	core <buildtarget>buildworld</buildtarget>,
-	<buildtarget>buildkernel</buildtarget>,
-	<buildtarget>installkernel</buildtarget>,
-	<buildtarget>installworld</buildtarget> sequence described in
-	the following paragraphs.  Other reasons for using these
-	steps are listed below:</para>
-
-      <itemizedlist>
-	<listitem>
-	  <para>The old world might not run correctly on the new
+      <title>Overview of Process</title>
+
+      <para>The build world process assumes an upgrade from an older &os;
+	version using the sources to a newer
+	version that were obtained using the instructions in 
+	<xref linkend="synching"/>.</para>
+	
+      <para><quote>World</quote> includes the &os; kernel, core system binaries,
+	libraries, programming files, and built-in compiler. The order in which these
+	components are built and installed is important.</para>
+	
+      <para>For example, the old compiler might have a bug and not be able to
+	    compile the new kernel.  Since the new kernel should be
+	    built with the new compiler, the new compiler
+	    must be built, but not necessarily installed, before the new kernel is built.</para>
+
+	    <para>The new world might rely on new kernel features,
+	    so the new kernel must be installed before the new world is
+	    installed.  The old world might not run correctly on the new
 	    kernel, so the new world must be installed immediately
 	    upon installing the new kernel.</para>
-	</listitem>
 
-	<listitem>
 	  <para>Some configuration changes must be made before the new
 	    world is installed, but others might break the old world.
 	    Hence, two different configuration upgrade steps are
-	    generally needed.</para>
-	</listitem>
-
-	<listitem>
-	  <para>For the most part, the update process only replaces or
+	    generally needed.  For the most part, the update process only replaces or
 	    adds files and existing old files are not deleted.  In a
 	    few cases, this can cause problems.  As a result, the
 	    update procedure will sometimes specify certain files that
-	    should be manually deleted at certain steps.  This may or
-	    may not be automated in the future.</para>
-	</listitem>
-      </itemizedlist>
+	    should be manually deleted at certain steps.</para>
 
-      <para>These concerns have led to the following recommended
-	sequence.  Note that the detailed sequence for particular
-	updates may require additional steps, but this core process
-	should remain unchanged for some time:</para>
+      <para>These concerns have led to the following recommended upgrade
+	sequence  described in
+	the following procedure.</para>
 
-      <orderedlist>
-	<listitem>
+    <procedure>
+      <title>Overview of Build World Process</title>
+
+    <para>The commands used in the build world process should be run in the order specified
+	here.  This section summarizes the function of each command.</para>
+      <step>
 	  <para><command>make
 	      buildworld</command></para>
 
@@ -1589,36 +1545,36 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	    tools, then uses the new compiler to compile the rest of
 	    the new world.  The result ends up in
 	    <filename>/usr/obj</filename>.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>make
 	      buildkernel</command></para>
 
 	  <para>This uses the <emphasis>new</emphasis> compiler
 	    residing in <filename>/usr/obj</filename> in order to
 	    protect against compiler-kernel mismatches.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>make
 	      installkernel</command></para>
 
 	  <para>Place the new kernel and kernel modules onto the disk,
 	    making it possible to boot with the newly updated
 	    kernel.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para>Reboot into single user mode.</para>
 
 	  <para>Single user mode minimizes problems from updating
 	    software that is already running.  It also minimizes any
 	    problems from running the old world on a new
 	    kernel.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>mergemaster
 	      -p</command></para>
 
@@ -1631,25 +1587,25 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	    <buildtarget>installworld</buildtarget> step will be able
 	    to use the newly installed system user or system group
 	    names without problems.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>make
 	      installworld</command></para>
 
 	  <para>Copies the world
 	    from <filename>/usr/obj</filename>.  The
 	    new kernel and new world are now installed on disk.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>mergemaster</command></para>
 
 	  <para>Repeated to update the remaining configuration files,
 	    now that the new world is on disk.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>make
 	      delete-old</command></para>
 
@@ -1659,24 +1615,24 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	    <filename>utmp.h</filename> causes problems in some ports
 	    when the new <filename>utmpx.h</filename> is
 	    installed.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para>Reboot.</para>
 
 	  <para>A full machine reboot is needed now to load the new
 	    kernel and new world with new configuration files.</para>
-	</listitem>
+	</step>
 
-	<listitem>
+	<step>
 	  <para><command>make
 	      delete-old-libs</command></para>
 
 	  <para>Remove any obsolete libraries to avoid conflicts with
 	    newer ones.  Make sure that all ports have been rebuilt
 	    before old libraries are removed.</para>
-	</listitem>
-      </orderedlist>
+	</step>
+      </procedure>
 
       <para>Upgrades from one release of the same &os; branch to a
 	more recent release of the same branch, such as from 9.0 to