Bug#929003: release-notes: Provide specific instructions to remove obsolete packages

["Karl O. Pinc" <kop@meme.com>]

On Wed, 15 May 2019 23:05:29 +0100
Justin B Rye <justin.byam.rye@gmail.com> wrote:

> Karl O. Pinc wrote:
> > Yes.  But you do "Preparing for the next release" _after_ upgrade.
> > My suggestion is to _also_ tell people to get rid of obsolete
> > packages before they start to upgrade.
> 
> Ah, now I see where it fits.  Okay, revised patch.

Your patch is fine.  Attached is an alternate patch with
a tweak the "text user interface" phrase to "textual
user interface" so as to be more recognizably
analogous with "graphical user interface".

Regards,

Karl <kop@meme.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

diff --git a/en/upgrading.dbk b/en/upgrading.dbk
index 30e138ab..97591735 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -308,6 +308,10 @@ $ apt-forktracer | sort
     <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see
     <xref linkend="old-sources"/>.
   </para>
+  <para>
+    It is a good idea to <link linkend="obsolete">remove obsolete
+    packages</link> from your system before upgrading.
+  </para>
 
   <section id="proposed-updates">
     <title>The proposed-updates section</title>
@@ -1266,8 +1270,8 @@ Errors were encountered while processing:
       can also use the following alternative to the commands above:
     </para>
     <screen>
-$ aptitude search '~c'
-$ aptitude purge '~c'
+# aptitude search '~c'
+# aptitude purge '~c'
     </screen>
   </section>
 
@@ -1295,11 +1299,16 @@ $ aptitude purge '~c'
     case, packages might still be present in the <quote>unstable</quote> distribution.
   </para>
   <para>
-    Detecting which packages in an updated system are <quote>obsolete</quote> is easy since the
-    package management front-ends will mark them as such.  If you are using
-    <command>aptitude</command>, you will see a listing of these packages in the
-    <quote>Obsolete and Locally Created Packages</quote> entry.
+    Some package management front-ends provide easy ways of finding installed
+    packages that are no longer available from any known repository. The
+    <command>aptitude</command> textual user interface lists them in the category
+    <quote>Obsolete and Locally Created Packages</quote>, and they can be listed
+    and purged from the commandline with:
   </para>
+  <screen>
+# aptitude search '~o'
+# aptitude purge '~o'
+  </screen>
   <para>
     The <ulink url="&url-bts;">Debian Bug Tracking System</ulink>
     often provides additional information on why the package was removed.  You