[Aptitude-devel] r3014 - in trunk/aptitude: . doc/en

[Daniel Burrows]

Author: dburrows
Date: Wed Apr 20 15:46:54 2005
New Revision: 3014

Modified:
   trunk/aptitude/ChangeLog
   trunk/aptitude/doc/en/manpage.xml
Log:
Document dist-upgrade.

Modified: trunk/aptitude/ChangeLog
==============================================================================
--- trunk/aptitude/ChangeLog	(original)
+++ trunk/aptitude/ChangeLog	Wed Apr 20 15:46:54 2005
@@ -1,3 +1,10 @@
+2005-04-20  Daniel Burrows  <dburrows@debian.org>
+
+	* doc/en/manpage.xml:
+
+	  Document dist-upgrade (with prodding from Branden).
+	  Closes: #268697.
+
 2005-04-17  Sorin Batariuc  <sorin@bonbon.net>
 
 	* Complete Romanian translation. Closes: #305282

Modified: trunk/aptitude/doc/en/manpage.xml
==============================================================================
--- trunk/aptitude/doc/en/manpage.xml	(original)
+++ trunk/aptitude/doc/en/manpage.xml	Wed Apr 20 15:46:54 2005
@@ -291,6 +291,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 +789,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>