Editorial review of Variables and Targets section.

Move note on scripting the process to above the process.
More commits to come.

Sponsored by:	iXsystems

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

@@ -1396,6 +1396,25 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	sequence  described in
 	the following procedure.</para>
 
+      <note>
+      <para>It is a good idea to save the output from running
+	<command>make</command> to a file.  If something goes wrong, a copy of
+	the error message can be posted to one of the &os; mailing
+	lists.</para>
+
+      <para>The easiest way to do this is to use <command>script</command> with a
+	parameter that specifies the name of the file to save all
+	output to.  Do not save the output to
+	<filename>/tmp</filename> as this directory may be cleared at
+	next reboot.  A better place to save the file is
+	<filename>/var/tmp</filename>.  Run this command immediately before rebuilding
+	the world, and then type <userinput>exit</userinput> when the
+	process has finished:</para>
+
+      <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
+Script started, output file is /var/tmp/mw.out</screen>
+      </note>
+
       <procedure>
 	<title>Overview of Build World Process</title>
 
@@ -1568,6 +1587,10 @@ before running "/usr/sbin/freebsd-update install"</screen>
       <para>This build world process uses several configuration
 	files.</para>
 
+      <para>The <filename>Makefile</filename> located in <filename>/usr/src</filename>
+	describes how the programs that comprise &os; should be
+	built and the order in which they should be built.</para>
+
       <para>The options available to <command>make</command> are described in
 	&man.make.conf.5; and some common examples are included in
 	<filename>/usr/share/examples/etc/make.conf</filename>.  Any
@@ -1597,140 +1620,70 @@ before running "/usr/sbin/freebsd-update install"</screen>
     </sect2>
 
     <sect2 xml:id="make-buildworld">
-      <title>Recompile the Base System</title>
+      <title>Variables and Targets</title>
 
-      <para>It is a good idea to save the output from running
+      <para>The general format for using <command>make</command> is as
-	&man.make.1; to a file.  If something goes wrong, a copy of
+	follows:</para>
-	the error message can be posted to one of the &os; mailing
-	lists.</para>
-
-      <para>The easiest way to do this is to use &man.script.1; with a
-	parameter that specifies the name of the file to save all
-	output to.  Run this command immediately before rebuilding
-	the world, and then type <userinput>exit</userinput> when the
-	process has finished:</para>
-
-      <screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
-Script started, output file is /var/tmp/mw.out
-&prompt.root; <userinput>make TARGET</userinput>
-<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>
-&prompt.root; <userinput>exit</userinput>
-Script done, &hellip;</screen>
-
-      <para><emphasis>Do not</emphasis> save the output in
-	<filename>/tmp</filename> as this directory may be cleared at
-	next reboot.  A better place to save the file is
-	<filename>/var/tmp</filename> or in <systemitem
-	  class="username">root</systemitem>'s home directory.</para>
-
-      <para>While in <filename>/usr/src</filename> type:</para>
-
-      <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
-
-      <indexterm>
-	<primary><command>make</command></primary>
-      </indexterm>
-
-      <para>To rebuild the world, use &man.make.1;.  This command
-	reads instructions from the <filename>Makefile</filename>,
-	which describes how the programs that comprise &os; should be
-	built and the order in which they should be built.</para>
-
-      <para>The general format of the command is as follows:</para>
 
       <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
 
       <para>In this example,
 	<option>-<replaceable>x</replaceable></option> is an option
-	passed to &man.make.1;.  Refer to &man.make.1; for examples
+	passed to <command>make</command>.  Refer to &man.make.1; for examples
 	of the available options.</para>
 
-      <para><option>-D<replaceable>VARIABLE</replaceable></option>
+      <para>To pass a variable, specify the variable name with <option>-D<replaceable>VARIABLE</replaceable></option>.
-	passes a variable to the <filename>Makefile</filename>.  The
+	The
 	behavior of the <filename>Makefile</filename> is controlled by
-	these variables.  These are the same variables as are set in
+	variables.  These can either be set in
-	<filename>/etc/make.conf</filename>, and this provides
+	<filename>/etc/make.conf</filename> or they can be specified
-	another way of setting them.  For example:</para>
+	when using <command>make</command>.  For example, this
+	variable specifies that profiled libraries
+	should not be built:</para>
 
       <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
 
-      <para>is another way of specifying that profiled libraries
+      <para>It corresponds with this setting in
-	should not be built, and corresponds with the</para>
+	<filename>/etc/make.conf</filename>:</para>
 
       <programlisting>NO_PROFILE=    true     #    Avoid compiling profiled libraries</programlisting>
 
-      <para>line in <filename>/etc/make.conf</filename>.</para>
+      <para>The <replaceable>target</replaceable> tells <command>make</command> what
-
+	to do and the <filename>Makefile</filename> defines the
-      <para><replaceable>target</replaceable> tells &man.make.1; what
+	available targets.  Some targets
-	to do.  Each <filename>Makefile</filename> defines a number of
-	different <quote>targets</quote>, and the choice of target
-	determines what happens.</para>
-
-      <para>Some targets listed in the <filename>Makefile</filename>
 	are used by the build process to break out the steps
 	necessary to rebuild the system into a number of
 	sub-steps.</para>
 
-      <para>Most of the time, no parameters need to be passed to
-	&man.make.1; and the command looks like this:</para>
-
-      <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
-
-      <para>Where <replaceable>target</replaceable> is one of many
-	build options.  The first target should always be
-	<buildtarget>buildworld</buildtarget>.</para>
-
-      <para>As the names imply, <buildtarget>buildworld</buildtarget>
-	builds a complete new tree under <filename>/usr/obj</filename>
-	and <buildtarget>installworld</buildtarget> installs this tree
-	on the current machine.</para>
-
       <para>Having separate options is useful for two reasons.  First,
-	it allows for a <quote>self hosted</quote> build that does not
+	it allows for a build that does not
 	affect any components of a running system.  Because of this,
-	<buildtarget>buildworld</buildtarget> can be run on a machine
+	<buildtarget>buildworld</buildtarget> can be safely run on a machine
-	running in multi-user mode with no fear of ill-effects.  It is
+	running in multi-user mode.  It is
 	still recommended that <buildtarget>installworld</buildtarget>
 	be run in part in single-user mode, though.</para>
 
-      <para>Secondly, it allows NFS mounts to be used to upgrade
+      <para>Secondly, it allows <acronym>NFS</acronym> mounts to be used to upgrade
-	multiple machines on a network.  If order to upgrade three
+	multiple machines on a network, as described in <xref
-	machines, <systemitem>A</systemitem>,
+	  linkend="small-lan"/>.</para>
-	<systemitem>B</systemitem> and <systemitem>C</systemitem>, run
-	<command>make buildworld</command> and <command>make
-	  installworld</command> on <systemitem>A</systemitem>.
-	<systemitem>B</systemitem> and <systemitem>C</systemitem>
-	should then NFS mount <filename>/usr/src</filename> and
-	<filename>/usr/obj</filename> from <systemitem>A</systemitem>,
-	and run <command>make installworld</command> to install the
-	results of the build on <systemitem>B</systemitem> and
-	<systemitem>C</systemitem>.</para>
-
-      <para>Although the <buildtarget>world</buildtarget> target still
-	exists, users are strongly encouraged not to use it.</para>
-
-      <para>Instead, run:</para>
-
-      <screen>&prompt.root; <userinput>make buildworld</userinput></screen>
 
       <para>It is possible to specify <option>-j</option> which will
 	cause <command>make</command> to spawn several simultaneous
-	processes.  This is most useful on multi-CPU machines.
+	processes.
-	However, since much of the compiling process is I/O bound
+	Since much of the compiling process is <acronym>I/O</acronym>-bound
-	rather than CPU bound, it is also useful on single CPU
+	rather than <acronym>CPU</acronym>-bound, this is useful on both single <acronym>CPU</acronym>
-	machines.</para>
+	and multi-<acronym>CPU</acronym> machines.</para>
 
-      <para>On a typical single-CPU machine, run:</para>
+      <para>On a single-<acronym>CPU</acronym> machine, run
-
+	the following command to have up to 4 processes running at
-      <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
-
-      <para>&man.make.1; will then have up to 4 processes running at
 	any one time.  Empirical evidence posted to the mailing lists
 	shows this generally gives the best performance
 	benefit.</para>
 
-      <para>On a multi-CPU machine using an SMP configured kernel, try
+      <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
-	values between 6 and 10 and see how they speed things
+
+      <para>On a multi-<acronym>CPU</acronym> machine, try
+	values between <literal>6</literal> and <literal>10</literal> to see how they speed things
 	up.</para>
 
       <indexterm>
@@ -1738,28 +1691,22 @@ Script done, &hellip;</screen>
 	<secondary>timings</secondary>
       </indexterm>
 
-      <para>Many factors influence the build time, but fairly recent
-	machines may only take a one or two hours to build the
-	&os.stable; tree, with no tricks or shortcuts used during the
-	process.  A &os.current; tree will take somewhat
-	longer.</para>
-
       <note>
-	<para>If variables were specified to
+	<para>If any variables were specified to
 	  <command>make buildworld</command>, specify the same
 	  variables to <command>make installworld</command>.  However,
-	  <option>-j</option> must never be used with
+	  <option>-j</option> must <emphasis>never</emphasis> be used with
 	  <buildtarget>installworld</buildtarget>.</para>
 
-	<para>For example, if you ran:</para>
+	<para>For example, if this command was used:</para>
 
 	<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
 
-	<para>install the results with:</para>
+	<para>Install the results with:</para>
 
 	<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
 
-	<para>otherwise, the command will try to install profiled
+	<para>Otherwise, the second command will try to install profiled
 	  libraries that were not built during the
 	  <command>make buildworld</command> phase.</para>
       </note>