Regarding the advice to avoid dist-upgrade...I was half-asleep when you brought that up, and I think I may have given bad advice as a result. dist-upgrade can cause problems, but if you don't use it from time to time you're guaranteed to end up with some stale packages (due to stuff that simply can't be upgraded without installing or removing packages). I'll probably try a slightly different angle on this. Any comments on the attached patch?
Daniel -- /------------------- Daniel Burrows <[EMAIL PROTECTED]> ------------------\ | Put no trust in cryptic comments. | \------ (if (not (understand-this)) (go-to http://www.schemers.org)) -------/
Index: doc/en/manpage.xml
===================================================================
--- doc/en/manpage.xml (revision 3013)
+++ doc/en/manpage.xml (working copy)
@@ -56,6 +56,7 @@
<arg choice='plain'>forget-new</arg>
<arg choice='plain'>update</arg>
<arg choice='plain'>upgrade</arg>
+ <arg choice='plain'>dist-upgrade</arg>
</group>
</cmdsynopsis>
@@ -291,6 +292,27 @@
</varlistentry>
<varlistentry>
+ <term><literal>dist-upgrade</literal></term>
+
+ <listitem>
+ <para>
+ Upgrades installed packages to their most recent version,
+ removing or installing packages as necessary. This
+ command is less conservative than
+ <literal>upgrade</literal> and thus more likely to perform
+ unwanted actions. Users are advised to either use
+ <literal>upgrade</literal> instead or to carefully inspect
+ the list of packages to be installed and removed.
+ </para>
+
+ <para>
+ See <quote><link linkend='secManBugs'>BUGS</link></quote>
+ below.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>forget-new</literal></term>
<listitem>
@@ -768,6 +790,20 @@
</variablelist>
</refsect1>
+ <refsect1 id='secManBugs'>
+ <title>Bugs</title>
+
+ <para><literal>dist-upgrade</literal> does not behave in a
+ terribly well-defined or well-understood fashion. The decisions
+ about how to resolve dependency problems are made by &apt;'s
+ problem resolver, which is fairly deep black magic. Furthermore,
+ the problem resolver is not aware of &aptitude;'s automatic
+ removal of obsolete packages, which can lead it to choose truly
+ terrible solutions to its problems (such as removing all of KDE to
+ resolve a broken dependency in a single package).
+ </para>
+ </refsect1>
+
<refsect1>
<title>See Also</title>
pgp8VSQF3Cw2m.pgp
Description: PGP signature
