--- chapter.sgml	2011-12-17 13:00:07.687792023 +0000
+++ /tmp/cutting-edge-new	2011-12-17 12:38:30.000000000 +0000
@@ -1967,6 +1967,16 @@
 	</listitem>
 
 	<listitem>
+	  <para><command>make <maketarget>delete-old</maketarget></command></para>
+
+	  <para>This target deletes old (obsolete) files.  This is important
+	    because sometimes they cause problems if left on the disk, for
+	    example the presence of the old <filename>utmp.h</filename> causes
+	    problems in some ports when the new
+	    <filename>utmpx.h</filename> is installed.</para>
+	</listitem>
+
+	<listitem>
 	  <para><command>mergemaster</command></para>
 
 	  <para>Now you can update the remaining configuration files, since
@@ -1979,6 +1989,14 @@
 	  <para>A full machine reboot is needed now to load the new kernel
 	    and new world with new configuration files.</para>
 	</listitem>
+
+	<listitem>
+	  <para><command>make <maketarget>delete-old-libs</maketarget></command></para>
+
+	  <para>Remove any obsolete libraries to avoid conflicts with newer
+	    ones.  Make sure that all ports have been rebuilt to use the new
+	    libraries before you delete the old ones.</para>
+	</listitem>
       </orderedlist>
 
       <para>Note that if you're upgrading from one release of the same &os;
@@ -2035,8 +2053,10 @@
 &prompt.root; <userinput>mergemaster -p</userinput>
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make installworld</userinput>
+&prompt.root; <userinput>make delete-old</userinput>
 &prompt.root; <userinput>mergemaster</userinput>
-&prompt.root; <userinput>reboot</userinput></screen>
+&prompt.root; <userinput>reboot</userinput>
+&prompt.root; <userinput>make delete-old-libs</userinput></screen>
 
       <warning>
 	<title>Read Further Explanations</title>
@@ -2482,9 +2502,11 @@
 	  </author>
 	</authorgroup>
       </sect2info>
-      <title>Deleting obsolete files, directories and libraries</title>
+
+      <title>Deleting obsolete files and directories</title>
+
       <indexterm>
-	<primary>Deleting obsolete files, directories and libraries</primary>
+	<primary>Deleting obsolete files and directories</primary>
       </indexterm>
 
       <para>As a part of the &os; development lifecycle, it happens from time
@@ -2503,14 +2525,13 @@
 	instructions will help you removing these obsolete files during the
 	system upgrade process.</para>
 
-      <para>We assume you are following the steps outlined in <xref
-	linkend="canonical-build">.  After the <command>make
+      <para>After the <command>make
 	<maketarget>installworld</maketarget></command> and the subsequent
 	<command>mergemaster</command> commands have finished successfully, you
 	should check for obsolete files and libraries as follows:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-  &prompt.root; <userinput>make check-old</userinput></screen>
+&prompt.root; <userinput>make check-old</userinput></screen>
 
       <para>If any obsolete files are found, they can be deleted using the
 	following commands:</para>
@@ -2789,8 +2810,8 @@
     <sect2 id="updating-upgrading-rebooting">
       <title>Rebooting</title>
 
-      <para>You are now done.  After you have verified that everything appears
-	to be in the right place you can reboot the system.  A simple
+      <para>You are now almost done.  After you have verified that everything
+	appears to be in the right place you can reboot the system.  A simple
 	&man.shutdown.8; should do it:</para>
 
       <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
@@ -2806,11 +2827,11 @@
 	  depend on those obsolete files.  This is especially true for old
 	  libraries. In most cases, you need to recompile the programs, ports,
 	  or libraries that used the old library before <command>make
-	  <maketarget>delete-old-libs</maketarget></command> is executed.</para>
+	<maketarget>delete-old-libs</maketarget></command> is executed.</para>
       </warning>
 
-      <para>Utilities for checking shared library dependencies are available from
-	the Ports Collection in <filename
+      <para>Utilities for checking shared library dependencies are available
+	from the Ports Collection in <filename
 	role="package">sysutils/libchk</filename> or <filename
 	role="package">sysutils/bsdadminscripts</filename>.</para>
 
@@ -2818,7 +2839,7 @@
 	causing messages like these:</para>
 
       <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
-  /usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
+/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
 
       <para>To solve these problems, determine which port installed the
 	library:</para>
@@ -2830,9 +2851,10 @@
 
       <para>Then deinstall, rebuild and reinstall the port. The <filename
 	role="package">ports-mgmt/portmaster</filename> and <filename
-	role="package">ports-mgmt/portupgrade</filename> utilities can be used to
-	automate this process.  After you've made sure that all ports are rebuilt
-	and do not use the old libraries anymore, you can delete them using the
+	role="package">ports-mgmt/portupgrade</filename> utilities can be used
+	to automate this process.  After you've made sure that all ports are
+	rebuilt and do not use the old libraries anymore, you can delete them
+	using the
 	following command:</para>
 
       <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
