Index: chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.233
diff -u -r1.233 chapter.sgml
--- chapter.sgml	24 Dec 2008 21:47:59 -0000	1.233
+++ chapter.sgml	26 Dec 2008 03:28:05 -0000
@@ -307,23 +307,6 @@
     <sect2>
       <title>Major and Minor Upgrades</title>
 
-      <para>This process will remove old object files and
-	libraries which will break most third party applications.
-	It is recommended that all installed ports either be removed
-	and re-installed or upgraded later using the
-	<filename role="package">ports-mgmt/portupgrade</filename>
-	utility.  Most users will want to run a test build using
-	the following command:</para>
-
-      <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
-
-      <para>This will ensure everything will be re-installed
-	correctly.  Note that setting the
-	<makevar>BATCH</makevar> environment variable to
-	<literal>yes</literal> will answer <literal>yes</literal> to
-	any prompts during this process, removing the need for
-	manual intervention during the build process.</para>
-
       <para>Major and minor version updates may be performed by
 	providing <command>freebsd-update</command> with a release
 	version target, for example, the following command will
@@ -410,19 +393,77 @@
 	  three.</para>
       </note>
 
-      <para>All third party software will now need to be rebuilt and
-	re-installed.  This is required as installed software may
-	depend on libraries which have been removed during the upgrade
-	process.  The
-	<filename role="package">ports-mgmt/portupgrade</filename>
-	command may be used to automate this process.  The following
-	commands may be used to begin this process:</para>
-
-      <screen>&prompt.root; <userinput>portupgrade -f ruby</userinput>
-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
-&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput>
-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
-&prompt.root; <userinput>portupgrade -af</userinput></screen>
+      <para>This process will remove old object files and
+	libraries which will break most third party applications.
+	Hence it is essential that all installed ports either be removed
+	and re-installed or upgraded by using a tool for managing
+	ports, see <xref linkend="ports-using">.</para>
+
+      <para>A procedure for accomplishing this task with
+	<application>Portmaster</application> (see <xref
+	linkend="portmaster">) is as follows.  Note that it is assumed
+	that ports are installed to <filename
+	  class="directory">/usr/local</filename>; adjust as
+	needed.</para>
+
+      <procedure>
+	<step>
+	  <para>Make a list of all installed ports:</para>
+
+	  <screen>&prompt.root; <userinput>portmaster -l &gt; <replaceable>installed-port-list</replaceable></userinput></screen>
+	</step>
+
+	<step>
+	  <para>Update the Ports&nbsp;Collection.</para>
+	</step>
+
+	<step>
+	  <para>Ask <application>Portmaster</application> to recurse
+	    through the installed ports to get a list of
+	    <filename>distinfo</filename> files, then recurse through
+	    all files in <filename
+	      class="directory">/usr/ports/distfiles</filename> to make
+	    sure that they are still associated with an installed port.
+	    If not, delete the stale file:</para>
+
+	  <screen>&prompt.root; <userinput>portmaster --clean-distfiles-all</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Fetch required distfiles to prepare to rebuild all
+	    upgraded ports:</para>
+
+	  <screen>&prompt.root; <userinput>portmaster -Faf</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Delete all installed packages:</para>
+
+	  <screen>&prompt.root; <userinput>pkg_delete -a</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Remove all shared libraries stored for backward
+	    compatibility, since they are not needed anymore:</para>
+
+	  <screen>&prompt.root; <userinput>rm -rf /usr/local/lib/compat/pkg</userinput></screen>
+
+	  <para>Do not forget to manually check through <filename
+	      class="directory">/usr/local</filename> to make sure it is
+	    really empty.</para>
+	</step>
+
+	<step>
+	  <para>Look at the list generated in the first step and install
+	    all the root and leaf ports that still needed.  The trunk
+	    and branch ports are dependencies, and will automatically be
+	    installed as needed.</para>
+
+	  <para>One may want to use the <option>-D</option> option for
+	    the installations and then run
+	    <option>--clean-distfiles-all</option> again.</para>
+	</step>
+      </procedure>
 
       <para>Once this has completed, finish the upgrade process with a
 	final call to <command>freebsd-update</command>.  Issue the