Bug#489132: upgrade apt/aptitude first

["Vincent.McIntyre@csiro.au" <Vincent.McIntyre@csiro.au>]

I'm finding this discussion of apt/aptitude somewhat confusing.
I rendered the text to html, did a proof-read, and came up with
the attached patch against r5510.

Does this help simplify things?
There are a handful of copy-editing changes along the way.

Cheers
Vince

Index: upgrading.dbk
===================================================================
--- upgrading.dbk	(revision 5510)
+++ upgrading.dbk	(working copy)
@@ -704,9 +714,9 @@
 <section id="aptupgrade1st">
   <title>Upgrade apt and/or aptitude first</title>
   <para>
-    Several bug reports have shown <systemitem
+    Several bug reports have shown that the versions of the <systemitem
     role="package">aptitude</systemitem> and <systemitem
-    role="package">apt</systemitem> in etch are often unable to
+    role="package">apt</systemitem> packages in etch are often unable to
     handle the upgrade to &releasename;. In &releasename;, <systemitem
     role="package">apt</systemitem> better deals with complex chains
     of packages requiring immediate configuration and <systemitem
@@ -714,28 +724,32 @@
     solutions for satisfying the dependencies. As these two features
     are heavily involved during the dist-upgrade to &releasename;, it
     is then required to upgrade those two packages before upgrading
-    anything else:
+    anything else. For <systemitem role="package">apt</systemitem>, run:
     <programlisting># apt-get install apt</programlisting>
-    (and <systemitem role="package">aptitude</systemitem>, if you have
-    used it before and want to re-use the automatically-installed
-    information) or
+    and for <systemitem role="package">aptitude</systemitem> (if you have
+    it installed) run:
     <programlisting># aptitude install aptitude</programlisting>
   </para>
 </section>
 <section id="aptconvert">
-  <title>Use aptitudes list of automatically-installed with apt</title>
+  <title>Using aptitude's list of automatically-installed packages with apt</title>
   <para>
+    <systemitem role="package">aptitude</systemitem> maintains a list
+    of packages that were installed automatically (for instance, as
+    dependencies of another package). In &releasename;, <systemitem
+    role="package">apt</systemitem> now has this feature as well.
+  </para>
+  <para>
     The first time the &releasename; version of <systemitem
     role="package">aptitude</systemitem> is run, it will read in its
     list of automatically installed packages and convert it for use
     with the &releasename; version of <systemitem
-    role="package">apt</systemitem> (which can handle
-    automatically-installed information). If you use <systemitem
-    role="package">apt</systemitem> as package manager, you should at
+    role="package">apt</systemitem>. If you have <systemitem
+    role="package">aptitude</systemitem> installed, you should at
     least issue one <systemitem role="package">aptitude</systemitem>
-    command to do the conversion. For instance, searching for no
-    package:
-    <programlisting>aptitude search "?false"</programlisting>
+    command to do the conversion. One way to do this is by searching for
+    a non-existent package:
+    <programlisting># aptitude search "?false"</programlisting>
 </para>
 </section>