[Aptitude-svn-commit] r4386 - in branches/aptitude-0.3/aptitude: .
doc/en doc/en/images
Daniel Burrows
dburrows at costa.debian.org
Fri Sep 30 22:27:58 UTC 2005
Author: dburrows
Date: Fri Sep 30 22:27:53 2005
New Revision: 4386
Added:
branches/aptitude-0.3/aptitude/doc/en/images/solution-explanation-snapshot.png (contents, props changed)
Modified:
branches/aptitude-0.3/aptitude/ChangeLog
branches/aptitude-0.3/aptitude/doc/en/aptitude.xml
branches/aptitude-0.3/aptitude/doc/en/images/broken-snapshot.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot2.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot3.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot4.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot5.png
branches/aptitude-0.3/aptitude/doc/en/images/solution-story-snapshot.png
Log:
More fully document the resolver.
Modified: branches/aptitude-0.3/aptitude/ChangeLog
==============================================================================
--- branches/aptitude-0.3/aptitude/ChangeLog (original)
+++ branches/aptitude-0.3/aptitude/ChangeLog Fri Sep 30 22:27:53 2005
@@ -1,5 +1,10 @@
2005-09-30 Daniel Burrows <dburrows at debian.org>
+ * doc/en/aptitude.xml:
+
+ More fully document the resolver (the prose is a little stilted
+ in some places but it'll do for a first draft).
+
* src/generic/problemresolver/model.tex:
Add a disclaimer regarding the stupidity-removal algorithm.
Modified: branches/aptitude-0.3/aptitude/doc/en/aptitude.xml
==============================================================================
--- branches/aptitude-0.3/aptitude/doc/en/aptitude.xml (original)
+++ branches/aptitude-0.3/aptitude/doc/en/aptitude.xml Fri Sep 30 22:27:53 2005
@@ -34,6 +34,16 @@
<!ENTITY package-information "<menuchoice><shortcut><keycap>enter</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Information</guimenuitem></menuchoice>">
<!ENTITY package-changelog "<menuchoice><shortcut><keycap>C</keycap></shortcut><guimenu>package</guimenu><guimenuitem>Changelog</guimenuitem></menuchoice>">
+ <!ENTITY resolver-examine "<menuchoice><shortcut><keycap>e</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Examine Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-apply "<menuchoice><shortcut><keycap>!</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Apply Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-next "<menuchoice><shortcut><keycap>.</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Next Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-previous "<menuchoice><shortcut><keycap>,</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Previous Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-first "<menuchoice><shortcut><keycap><</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>First Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-last "<menuchoice><shortcut><keycap>></keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Last Solution</guimenuitem></menuchoice>">
+ <!ENTITY resolver-reject "<menuchoice><shortcut><keycap>r</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Toggle Rejected</guimenuitem></menuchoice>">
+ <!ENTITY resolver-approve "<menuchoice><shortcut><keycap>a</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>Toggle Approved</guimenuitem></menuchoice>">
+ <!ENTITY resolver-view-target "<menuchoice><shortcut><keycap>Enter</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>View Target</guimenuitem></menuchoice>">
+
<!ENTITY search-find "<menuchoice><shortcut><keycap>/</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Find</guimenuitem></menuchoice>">
<!ENTITY search-find-back "<menuchoice><shortcut><keycap>\</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Find Backwards</guimenuitem></menuchoice>">
<!ENTITY search-refind "<menuchoice><shortcut><keycap>n</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Find Again</guimenuitem></menuchoice>">
@@ -1092,7 +1102,7 @@
</imageobject>
<textobject role='text'>
-<screen> Actions Undo Package Search Options Views Help
+<screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
aptitude 0.3.3 #Broken: 1 Will free 48.6MB of disk space
i A nautilus 2.10.1-4 2.10.1-4
@@ -1160,12 +1170,12 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Keep the following packages at their current version:
- gstreamer0.8-cdparanoia [0.8.11-1 (unstable, now)]
- sound-juicer [2.10.1-3 (unstable, now)]
+ gstreamer0.8-cdparanoia [0.8.10-1 (unstable, now)]
+ sound-juicer [2.10.1-2 (now)]
@@ -1205,7 +1215,7 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Keep the following packages at their current version:
@@ -1253,7 +1263,7 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Keep the following packages at their current version:
@@ -1320,7 +1330,7 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Remove the following packages:
@@ -1386,7 +1396,7 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Remove the following packages:
@@ -2153,6 +2163,117 @@
</section>
<section>
+ <title>The Resolver Menu</title>
+
+ <figure>
+ <title>Commands available in the Resolver menu</title>
+
+ <informaltable>
+ <tgroup cols='2'>
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>&resolver-examine;</entry>
+
+ <entry>
+ Display a detailed description of the problem
+ resolver's current suggestion (see <xref
+ linkend='secResolver'/>).
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-apply;</entry>
+
+ <entry>
+ Carry out the actions that the problem resolver
+ is currently suggesting.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-next;</entry>
+
+ <entry>
+ Select the problem resolver's next suggestion.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-previous;</entry>
+
+ <entry>
+ Select the problem resolver's previous suggestion.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-first;</entry>
+
+ <entry>
+ Select the problem resolver's first suggestion.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-last;</entry>
+
+ <entry>
+ Select the problem resolver's most recently
+ generated solution (see <xref
+ linkend='secResolver'/>).
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-reject;</entry>
+
+ <entry>
+ When examining a solution, toggle whether the
+ currently selected action is rejected and move
+ to the next action (see <xref
+ linkend='secResolver'/>). If the action is
+ currently approved, its approval will be
+ cancelled.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-approve;</entry>
+
+ <entry>
+ When examining a solution, toggle whether the
+ currently selected action is approved and move
+ to the next action (see <xref
+ linkend='secResolver'/>). If the action is
+ currently rejected, its rejection will be
+ cancelled.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&resolver-view-target;</entry>
+
+ <entry>
+ When examining a solution, view detailed
+ information about the package which is affected
+ by the currently selected action (see <xref
+ linkend='secResolver'/>).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </figure>
+ </section>
+
+ <section>
<title>The Search Menu</title>
<figure>
@@ -3231,18 +3352,18 @@
</imageobject>
<textobject role='text'>
-<screen> Actions Undo Package Search Options Views Help
+<screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
-aptitude 0.3.3 #Broken: 1 Will free 1335kB of disk space
- --- admin - Administrative utilities (install software, manage users, etc)
- --- base - The Debian base system
- --- devel - Utilities and programs for software development
- --- doc - Documentation and specialized programs for viewing documentation
- --- games - Games, toys, and fun programs
- --\ gnome - The GNOME Desktop System
- --\ main - The main Debian archive
-i grip 3.3.1-2 3.3.1-4
-ipA sound-juicer -1245kB 2.10.1-2 2.10.1-3
+aptitude 0.3.3 #Broken: 1 Will free 48.6MB of disk space
+i A nautilus 2.10.1-4 2.10.1-4
+i nautilus-cd-burner 2.10.2-1.1 2.10.2-1.1
+i A nautilus-data 2.10.1-4 2.10.1-4
+i netspeed 0.12.1-1 0.12.1-1
+i A oaf 0.6.10-3 0.6.10-3
+i pybliographer 1.2.6.2-1 1.2.6.2-1
+i rhythmbox 0.8.8-13 0.8.8-13
+i shermans-aquarium 3.0.1-1 3.0.1-1
+idA sound-juicer -1733kB 2.10.1-3 2.10.1-3
GNOME 2 CD Ripper
sound-juicer will be removed.
@@ -3251,9 +3372,9 @@
removal:
- * gnome-desktop-environment depends on sound-juicer (>= 2.10.1)
+ * gnome-desktop-environment depends on sound-juicer
-[1/...] Suggest 2 keeps
+[1(1)/...] Suggest 2 keeps
e: Examine !: Apply .: Next ,: Previous</screen>
</textobject>
</mediaobject>
@@ -3264,8 +3385,9 @@
additional solutions by pressing <keycap>.</keycap> and
<keycap>,</keycap>, apply the current solution by pressing
<keycap>!</keycap>, and examine the solution in more detail
- by pressing <keycap>e</keycap>. Examining a solution will
- display a screen like this:
+ by pressing <keycap>e</keycap>. When you examine the
+ current solution, a screen similar to the following will
+ appear:
</para>
<screenshot>
@@ -3275,7 +3397,7 @@
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
--\ Keep the following packages at their current version:
@@ -3297,33 +3419,106 @@
-[1/...] Suggest 2 keeps
+[1(1)/...] Suggest 2 keeps
e: Examine !: Apply .: Next ,: Previous</screen>
</textobject>
</mediaobject>
</screenshot>
<para>
- For a more detailed explanation of why &aptitude; made the
- decisions that it did, press <keycap>o</keycap>. This will
- re-order the list according to dependencies, showing which
- dependency triggered each action in the list.
+ You can access information about the package affected by an
+ action by simply pressing <keycap>Enter</keycap> while the
+ package is highlighted. For a more detailed explanation of
+ why &aptitude; made a particular decision, you can highlight
+ the element in the list. When you do so, the lower half of
+ the screen will display the dependency which was resolved by
+ &aptitude;'s choice, along with every way in which this
+ dependency could have been resolved.
</para>
<screenshot>
<mediaobject>
<imageobject>
- <imagedata fileref='images/solution-story-snapshot.png' format='PNG'/>
+ <imagedata fileref='images/solution-explanation-snapshot.png' format='PNG'/>
</imageobject>
<textobject role='text'>
- <screen> Actions Undo Package Search Options Views Help
+ <screen> Actions Undo Package Resolver Search Options Views Help
f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
Packages Resolve Dependencies
- --\ gnome-desktop-environment depends upon sound-juicer (>= 2.10.1)
- -> Cancel the removal of sound-juicer
- --\ sound-juicer depends upon gstreamer0.8-cdparanoia
- -> Cancel the removal of gstreamer0.8-cdparanoia
+ --\ Keep the following packages at their current version:
+ gstreamer0.8-cdparanoia [0.8.11-1 (unstable, now)]
+ sound-juicer [2.10.1-3 (unstable, now)]
+
+
+
+
+
+
+cdparanoia plugin for GStreamer
+sound-juicer depends upon gstreamer0.8-cdparanoia
+--\ The following actions will resolve this dependency:
+ -> Downgrade sound-juicer [2.10.1-3 (unstable, now) -> 0.6.1-2 (testing)]
+ -> Remove sound-juicer [2.10.1-3 (unstable, now)]
+ -> Cancel the removal of gstreamer0.8-cdparanoia
+ -> Downgrade gstreamer0.8-cdparanoia [0.8.11-1 (unstable, now) -> 0.8.8-3 (tes
+
+
+
+[1(1)/...] Suggest 2 keeps
+e: Examine !: Apply .: Next ,: Previous</screen>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ You can guide the dependency resolver to a solution of which
+ you approve by <firstterm>approving</firstterm> or
+ <firstterm>rejecting</firstterm> the individual actions of a
+ solution. If you <firstterm>approve</firstterm> an action,
+ the resolver will choose it whenever possible, ignoring
+ alternatives (when there are several approved alternatives,
+ all of them will be chosen). On the other hand, if you
+ <firstterm>reject</firstterm> an action, the resolver will
+ never choose that action.
+ </para>
+
+ <para>
+ To reject a solution, highlight it and press
+ <keycap>r</keycap>; the rejection can be cancelled by
+ pressing <keycap>r</keycap> again. Similarly, select an
+ action and press <keycap>a</keycap> to approve it. You can
+ undo either action by using &undo-undo; while the resolver
+ screen is active. If you cancel a rejection or an approval,
+ any solutions that were ignored will be available the next
+ time that you generate a new solution.
+ </para>
+
+ <para>
+ Rejected actions are colored red and marked with an
+ <quote>R</quote>, while approved actions are colored green
+ and marked with an <quote>A</quote>. You can see this in
+ the following screenshot, where the action <quote>keep
+ <systemitem>gstreamer0.8-cdparanoia</systemitem> at its
+ current version</quote> has been rejected, and the action
+ <quote>keep <systemitem>sound-juicer</systemitem> at its
+ current version</quote> has been approved.
+ </para>
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='images/solution-reject-and-approve-snapshot.png' format='PNG'/>
+ </imageobject>
+
+ <textobject role='text'>
+ <screen> Actions Undo Package Resolver Search Options Views Help
+f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
+ Packages Resolve Dependencies
+ --\ Keep the following packages at their current version:
+R gstreamer0.8-cdparanoia [0.8.11-1 (unstable, now)]
+A sound-juicer [2.10.1-3 (unstable, now)]
+
@@ -3339,61 +3534,90 @@
-[1/...] Suggest 2 keeps
+[1(1)/...] Suggest 2 keeps
e: Examine !: Apply .: Next ,: Previous</screen>
</textobject>
</mediaobject>
</screenshot>
<para>
- In order to more efficiently find a solution that you
- approve of, you can direct &aptitude; to display only
- solutions which satisfy conditions that you choose.
+ Rejections and approvals only affect <emphasis>newly
+ generated</emphasis> solutions. You can tell when a new
+ solution will be generated by examining the indicator in the
+ lower left hand corner of the screen: if there is a number
+ in parentheses, it is the number of solutions that have been
+ generated. Thus, when the number outside the parentheses
+ and the number inside are identical (as above), pressing
+ <keycap>.</keycap> will generated a new solution. If there
+ is no number in parentheses (for instance, the indicator
+ reads <literal>[1/5]</literal>), then there are no more
+ solutions to generated. At any time, you can select the
+ last generated solution by pressing <keycap>></keycap>,
+ and the first generated solution by pressing
+ <keycap><</keycap>.
+ </para>
+
+ <important>
+ <para>
+ The state of the problem resolver is discarded when you
+ modify the state of any package. If you mark a package
+ for installation, for upgrade, for removal, etc, the
+ resolver will forget all of your rejections and approvals,
+ as well as all the solutions that have been generated so
+ far.
+ </para>
+ </important>
+
+ <para>
+ In addition to selecting actions in the list at the top of
+ the screen, you can also select them using the list in the
+ bottom half. To access this list, either click in it using
+ the mouse or press <keycap>Tab</keycap>. Finally, to see
+ the decisions that the problem resolver took arranged in
+ order, press <keycap>o</keycap>. This will give a list of
+ the dependencies that were resolved and the action taken to
+ resolve them, as in the following screenshot.
</para>
- <itemizedlist>
- <listitem>
- <para>
- To force aptitude to ignore solutions containing a
- particular action, highlight the action and press
- <keycap>r</keycap> to <quote>reject</quote> that action.
- Once you reject a particular action, any new solutions
- that you generate (i.e., solutions that have not yet
- been displayed) will not contain that action.
- </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='images/solution-story-snapshot.png' format='PNG'/>
+ </imageobject>
- <para>
- To cancel the rejection of an action, highlight the
- action again and press <keycap>r</keycap>.
- </para>
- </listitem>
+ <textobject role='text'>
+ <screen> Actions Undo Package Resolver Search Options Views Help
+f10: Menu ?: Help q: Quit u: Update g: Download/Install/Remove Pkgs
+ Packages Resolve Dependencies
+ --\ gnome-desktop-environment depends upon sound-juicer
+ -> Cancel the removal of sound-juicer
+ --\ sound-juicer depends upon gstreamer0.8-cdparanoia
+ -> Cancel the removal of gstreamer0.8-cdparanoia
- <listitem>
- <para>
- To force aptitude to only generate solutions containing
- a particular action, highlight the action and press
- <keycap>a</keycap> to <quote>accept</quote> that action.
- Once you accept a particular action, any new solutions
- that you generate will contain that action.
- </para>
- <para>
- To cancel the acceptance of an action, highlight the
- action again and press <keycap>a</keycap>.
- </para>
- <note>
- <para>
- Rejecting one action does not affect whether other
- actions are rejected or not. However, the same is not
- true when accepting an action. Accepting an action
- will automatically reject all alternatives to the
- action, even if those alternatives were previously
- unrejected or even accepted.
- </para>
- </note>
- </listitem>
- </itemizedlist>
+
+
+GNOME 2 CD Ripper
+gnome-desktop-environment depends upon sound-juicer
+--\ The following actions will resolve this dependency:
+ -> Remove gnome-desktop-environment [1:2.10.2.3 (unstable, testing, now)]
+ -> Cancel the removal of sound-juicer
+ -> Downgrade sound-juicer [2.10.1-3 (unstable, now) -> 0.6.1-2 (testing)]
+
+
+
+
+[1(1)/...] Suggest 2 keeps
+e: Examine !: Apply .: Next ,: Previous</screen>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ You can leave this display mode by pressing
+ <keycap>o</keycap> again.
+ </para>
</section>
<section id='secInstallRun'>
Modified: branches/aptitude-0.3/aptitude/doc/en/images/broken-snapshot.png
==============================================================================
Binary files. No diff available.
Added: branches/aptitude-0.3/aptitude/doc/en/images/solution-explanation-snapshot.png
==============================================================================
Binary file. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot.png
==============================================================================
Binary files. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot2.png
==============================================================================
Binary files. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot3.png
==============================================================================
Binary files. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot4.png
==============================================================================
Binary files. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-screen-snapshot5.png
==============================================================================
Binary files. No diff available.
Modified: branches/aptitude-0.3/aptitude/doc/en/images/solution-story-snapshot.png
==============================================================================
Binary files. No diff available.
More information about the Aptitude-svn-commit
mailing list