There has been much discussion about how bad "make world" is for people

who don't know exactly what they are doing, how it has caused a significant
amount of foot-shooting, etc.  This patch cleans up some handbook references
to "make world" and gives a brief note about why it's bad.

Reviewed by:	doc@
Revisions from:	linimon, simon

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

@@ -61,7 +61,7 @@
 	  <application>CTM</application>.</para>
       </listitem>
       <listitem><para>How to rebuild and reinstall the entire base
-      system with <command>make world</command>.</para>
+      system with <command>make buildworld</command> (etc).</para>
       </listitem>
 
     </itemizedlist>
@@ -536,10 +536,10 @@
   </sect1>
 
   <sect1 id="makeworld">
-    <title>Using <command>make world</command></title>
+    <title>Rebuilding <quote>world</quote></title>
 
     <indexterm>
-      <primary><command>make world</command></primary>
+      <primary>Rebuilding <quote>world</quote></primary>
     </indexterm>
     <para>Once you have synchronized your local source tree against a
       particular version of &os; (&os.stable;, &os.current;, and so on)
@@ -556,7 +556,8 @@
 	when you make mistakes, or when mistakes made by others in the
 	source tree render your system unbootable.</para>
 
-      <para>Make sure you have taken a backup.  And have a fixit floppy to
+      <para>Make sure you have taken a backup.  And have a fixit floppy or
+	bootable CD at
 	hand.  You will probably never have to use it, but it is better to be
 	safe than sorry!</para>
     </warning>
@@ -587,6 +588,17 @@
 	asking for trouble.</para>
     </warning>
 
+    <warning>
+      <title>Do not use <command>make world</command></title>
+
+      <para>A lot of older documentation recommends using
+	<command>make world</command> for this.  Doing that skips
+	some important steps and should only be used if you are
+	sure of what you are doing.  For almost all circumstances
+	<command>make world</command> is the wrong thing to do, and
+	the procedure described here should be used instead.</para>
+    </warning>
+
     <sect2>
       <title>The Canonical Way to Update Your System</title>
 
@@ -678,9 +690,11 @@
 	<filename>/etc/group</filename>.</para>
 
       <para>There have been occasions when the installation part of
-        <quote>make world</quote> has expected certain usernames or groups
+        <quote>make installworld</quote> has expected certain usernames or groups
 	to exist.  When performing an upgrade it is likely that these
-	users or groups did not exist. This caused problems when upgrading.</para>
+	users or groups did not exist. This caused problems when upgrading.
+	In some cases <quote>make buildworld</quote> will check to see if
+	these users or groups exist.</para>
 
       <para>A recent example of this is when the
 	<username>smmsp</username> user was added.  Users had the
@@ -785,7 +799,7 @@
 	<filename>/usr/obj</filename>.  The directories shadow those under
 	<filename>/usr/src</filename>.</para>
 
-      <para>You can speed up the <quote>make world</quote> process, and
+      <para>You can speed up the <quote>make buildworld</quote> process, and
 	possibly save yourself some dependency headaches by removing this
 	directory as well.</para>
 
@@ -895,7 +909,10 @@ Script done, &hellip;</screen>
 	  &os.stable; midway between 2.2.2 and 2.2.5) the
 	  <maketarget>world</maketarget> target has been split in
 	  two: <maketarget>buildworld</maketarget> and
-	  <maketarget>installworld</maketarget>.</para>
+	  <maketarget>installworld</maketarget>.  Beginning with version
+	  5.3 of &os the <maketarget>world</maketarget> will be changed
+	  so it will not work at all by default because it is actually
+	  dangerous for most users.</para>
 
 	<para>As the names imply, <maketarget>buildworld</maketarget>
 	  builds a complete new tree under <filename>/usr/obj</filename>,
@@ -955,7 +972,7 @@ Script done, &hellip;</screen>
       <sect3>
 	<title>Timings</title>
 	<indexterm>
-	  <primary><command>make world</command></primary>
+	  <primary>Rebuilding <quote>world</quote></primary>
 	  <secondary>timings</secondary>
 	</indexterm>
 
@@ -1069,7 +1086,7 @@ Script done, &hellip;</screen>
     </sect2>
 
     <sect2>
-      <title>Update Files Not Updated by <command>make world</command></title>
+      <title>Update Files Not Updated by <command>make installworld</command></title>
       
       <para>Remaking the world will not update certain directories (in
 	particular, <filename>/etc</filename>, <filename>/var</filename> and
@@ -1511,14 +1528,14 @@ Script done, &hellip;</screen>
       
 	    <para><filename>/usr/obj</filename> contains all the object files
 	      that were produced during the compilation phase.  Normally, one
-	      of the first steps in the <quote>make world</quote> process is to
+	      of the first steps in the <quote>make buildworld</quote> process is to
 	      remove this directory and start afresh.  In this case, keeping
 	      <filename>/usr/obj</filename> around after you have finished
 	      makes little sense, and will free up a large chunk of disk space
 	      (currently about 340&nbsp;MB).</para>
       
 	    <para>However, if you know what you are doing you can have
-	      <quote>make world</quote> skip this step.  This will make subsequent
+	      <quote>make buildworld</quote> skip this step.  This will make subsequent
 	      builds run much faster, since most of sources will not need to
 	      be recompiled.  The flip side of this is that subtle dependency
 	      problems can creep in, causing your build to fail in odd ways.
@@ -1539,7 +1556,7 @@ Script done, &hellip;</screen>
 	      you found a problem.</para>
 
 	    <para><emphasis>In general</emphasis> (and this is not a hard and
-	      fast rule) the <quote>make world</quote> process builds new
+	      fast rule) the <quote>make buildworld</quote> process builds new
 	      copies of essential tools (such as &man.gcc.1;, and
 	      &man.make.1;) and the system libraries.  These tools and
 	      libraries are then installed.  The new tools and libraries are
@@ -1557,7 +1574,7 @@ Script done, &hellip;</screen>
 &prompt.root; <userinput>make -DNOCLEAN all</userinput></screen>
 
 	    <para>This will not undo the work of the previous
-	      <quote>make world</quote>.</para>
+	      <quote>make buildworld</quote>.</para>
 
 	    <para>If you see the message:</para>
 
@@ -1565,7 +1582,7 @@ Script done, &hellip;</screen>
 Building everything..
 --------------------------------------------------------------</screen>
 
-	    <para>in the <quote>make world</quote> output then it is
+	    <para>in the <quote>make buildworld</quote> output then it is
 	      probably fairly safe to do so.</para>
 	    
 	    <para>If you do not see that message, or you are not sure, then it
@@ -1740,7 +1757,8 @@ Building everything..
 	<emphasis>build machine</emphasis>.  It is going to be the
 	machine that the world and kernel are built on. Ideally, it
 	should be a fast machine that has sufficient spare CPU to
-	run <command>make world</command>.  You will also want to
+	run <command>make buildworld</command> and
+	<command>make buildkernel</command>.  You will also want to
 	choose a machine to be the <emphasis>test
 	machine</emphasis>, which will test software updates before they
 	are put into production.  This <emphasis>must</emphasis> be a