Correct some parts based on feedback and suggestions by netchild:

- add more explanations about why it is a good idea to remove old libs
- move the "make delete-old" step after the second mergemaster, because
that is safer [1]
- remove the extra "make check-old-libs" because it is done together with
"make check-old"
- BATCH_DELETE_OLD_FILES is a make variable and not an environment variable
- warn more vividly that the user has to recompile ports and other programs
before running "make delete-old-libs" and explain how to do this
- mention that portupgrade can also be used to recompile ports

[1] this brings the handbook in sync with the description in
/usr/src/UPDATING changed in r216591.

Discussed with:     netchild

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

@@ -3037,31 +3037,33 @@ Building everything..
 
     <para>As a part of the &os; development lifecycle, it happens from time
       to time that files and their contents become obsolete.  This may be
-      because their functionality is implemented elsewhere or is removed from
-      the system entirely.  This includes old files, libraries and
-      directories, which should be removed when updating the system.  The
-      benefit for the user is that the system is not cluttered with old files
-      which take up unnecessary space on the storage (and backup) medium.  The
-      files, directories, and libraries that are considered obsolete are listed
-      in <filename>/usr/src/ObsoleteFiles.inc</filename>.  The following
+      because their functionality is implemented elsewhere, the version number
+      of the library has changed or it was removed from the system entirely.
+      This includes old files, libraries and directories, which should
+      be removed when updating the system.  The benefit for the user is that
+      the system is not cluttered with old files which take up unnecessary
+      space on the storage (and backup) medium.  Additionally, if the old
+      library had a security or stability issue, you should update to the
+      newer library to keep your system safe and prevent crashes caused by
+      the old library implementation.  The files, directories, and libraries
+      that are considered obsolete are listed in
+      <filename>/usr/src/ObsoleteFiles.inc</filename>.  The following
       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
-      <maketarget>installworld</maketarget></command> command completed
-      successfully, you should check for obsolete files and libraries as
-      follows:</para>
+      <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>
-&prompt.root; <userinput>make check-old-libs</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>
 
-    <screen>&prompt.root; <userinput>make delete-old</userinput>
-&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+    <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
 
     <tip>
       <para>See <filename>/usr/src/Makefile</filename>
@@ -3070,23 +3072,29 @@ Building everything..
 
     <para>A prompt is displayed before deleting each obsolete file.  You can
       skip the prompt and let the system remove these files automatically by
-      setting the <makevar>BATCH_DELETE_OLD_FILES</makevar> environment
-      variable to <literal>yes</literal>.  You can also achieve the same goal
-      by piping these commands through <command>yes</command> like this:</para>
+      using the <makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as
+      follows:<para>
 
-    <screen>&prompt.root; <userinput>yes|make delete-old</userinput>
-&prompt.root; <userinput>yes|make delete-old-libs</userinput></screen>      
+    <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
+
+    <para>You can also achieve the same goal by piping these commands through
+      <command>yes</command> like this:</para>
+
+    <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
 
     <warning>
       <title>Warning</title>
         <para>Deleting obsolete files will break applications that still
-          depend on those obsolete files.</para>
+          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>
     </warning>
 
     <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>
+      the Ports Collection in <filename
+      role="package">sysutils/libchk</filename> or <filename
+      role="package">sysutils/bsdadminscripts</filename>.</para>
 
     <para>Obsolete shared libraries can conflict with newer libraries,
       causing messages like these:</para>
@@ -3103,8 +3111,13 @@ Building everything..
 /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
 
     <para>Then deinstall, rebuild and reinstall the port. The <filename
-      role="package">ports-mgmt/portmaster</filename> utility can be used to
-      automate this process.</para>
+      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
+      following command:</para>
+
+    <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
   </sect1>
 
   <sect1 id="small-lan">