                                   APTITUDE

  Aptitude is the tentative name for a new curses-based frontend to apt.
Currently this is just a collection of a lot of different apt-related UI
elements and actions; there is not much central cohesion.  However, it is
actually very close to having a superset of dselect and console-apt's
capabilities, and being much more flexible to boot.

  This is the README file for the most recent public release of
Aptitude, version 0.0.4.  It describes how to compile and run the program.  An
overview of the code can be found in aptitude-hackers-guide.txt, and the
world domination plan--er, I mean TODO list--can be found in TODO.

  Aptitude is released under the GNU GPL, version 2.0 or later.  As usual, I
make no guarantees whatsoever, use at your own risk, etc.  See COPYING for
more information.

                                INSTALLATION

  This should really be in INSTALL, but how many of you read that?  Never mind.

  To compile the program, just type "./compile && make".  You must have
the libapt-pkg-dev Debian package installed to do this.  Note that it probably
doesn't make sense to compile Aptitude on a non-Debian system, although you're
welcome to try :-)  aptitude also is likely to require both Linux and ncurses,
although I am happy to accept patches to fix this using autoconf.  It'll get
fixed eventually anyway; the dependency *should* be limited to SIGWINCH,
term_resize(), and the terminal ioctls used to check resizing.  If nothing else
I can #ifdef the resize-checking out on other platforms.

  To run the program, execute the file "aptitude" which is produced by the
build.  Note that unlike many APT frontends, aptitude need not be run as root.
However, if you run it as a non-root user, you will be unable to install or
remove packages, or update the package lists.

                                  USAGE

  The interface should be fairly straightforward if you've seen this sort
of program before: there's a list of packages presented, out of which you can
select one using the arrow keys.  The currently selected package is
highlighted.
  If an error occurs, the status bar will turn red and a message will be
displayed.  Pressing a key should remove the message (sometimes, if the program
is busy, it may take a few seconds)  There are a few quirks with this, which I
hope to fix in the next release.

  More precisely, the following keys are available by default.

Up arrow: move up one package
Down arrow: move down one package
Enter: expand or collapse a tree, or view information about a package
'^' (caret): move to the tree containing the current item
'+': as in dselect, mark the current package to be upgraded or installed in the
    next package run.  Note that aptitude does not yet automagically fulfill
    dependencies (unless the apt libraries do something behind my back on an
    install run; they might, I haven't tested this because I intend to handle
    this very differently in the future).  The reason is that it's easy to
    end up with way too many packages installed by accident; I'm going to try
    to at least reduce the odds of this happening, by making it easy to see
    what happened.  However, if a package can't be installed due to dependency
    problems (it'll turn red), press "d" to see its dependencies.  Unfulfilled
    dependencies will be red, and you can choose what to install that way.
'-': sort of like dselect; decrease the 'install-ness' of a package by one.
   That is: if a package would be upgraded, it is placed on hold; if it would
   be installed, it is left uninstalled, and if it would be left alone or held,
   it is marked for removal.
'=': Place the package on hold (this works even if it's not upgradable)
'_': mark the package for purge.  Currently no visual distinction is made
   between packages to be purged and packages to be removed, and you can't
   switch straight from one to the other (hit '+-').  This ought to change.

  Currently '+' and '-' do not work on package groups.  This is not because
it's hard to do -- it's about 3 lines of code -- but rather because I'm
undecided on what the proper behavior of '+' and '-' on a group is.  Also,
it's really easy to screw things up this way, so I don't want to enable
it until I have undo capabilities.

'i': show the description of a package (yes, bad keybinding, will change)
'd': show the dependencies of a package
'v': show available versions of a package
'u': update the lists of available packages
'g': perform an install run
'f': forget all about which packages are 'new'
'q': leave the current screen (may exit the program)
'/': search for a package (currently only searches package names with straight
    string matching)  You can edit the string to search for with backspace,
    and start the search with enter (obvious, but more complex editing keys
    will be available in the future..)

  As you may notice, aptitude displays packages in a color-coded fashion.
The meaning is this:

-> Black background: package is OK and will not have any modifications made to
  it on the next run.
   If the package is in bold print, it is currently installed.
-> Red background: package is broken, or candidate version cannot be installed.
-> Blue background: this package will be upgraded on the next run.
-> White background: this package could be upgraded, but the upgrade has
  been overridden (=hold).
-> Green background: this package will be installed on the next run.
-> Magenta background: this package will be removed on the next run.

   Obviously this sucks for people on black-and-white terminals.  However:
 -> It looks great in an xterm and the Linux console (actually, the console
   has some issues with the progress bars, due to VGA's broken handling of
   yellow backgrounds -- they look brown, which is rather ugly.  You probably
   want to redefine the colors if you use Aptitude on the console a lot; see
   below for more information on this)
 -> I want to eventually allow the user to select between several styles of
   display of things like this.  It should be easier than you might think --
   probably all that has to be changed is colorization (maybe not even that)
   and formatting within each line.  In particular, a strict dselect lookalike
   is a must.

                                     CONFIGURATION

   All configuration for Aptitude is stored in apt.conf .  If you don't know
the syntax of this file, please go read apt.conf(5) or you won't be able
to understand what I'm saying! :)

                                      KEYBINDINGS
  As of version 0.0.3, Aptitude has support for configurable keybindings.
These are set in /etc/apt.conf, in the group Aptitude::UI::Keybindings.  You
can list any number of keybindings in this group; the format is:
BindingFoo "key1,key2,key3,keyn";
  where BindingFoo is the name of the function whose binding you wish to
reassign, and key1..keyn are the keys to which it should be bound.  Note that
these binding assignments will overrule any previous bindings for the function!

  Keys can be specified either by a single character, or by a symbolic name.
All the KEY_ constants are (or should) be accessable via names; the most
useful ones are:
tab
space
down
left
right
home
end
backspace
delete (?)
insert
pagedown
pageup
return (or enter)

  Key names are case-insensitive.  The full list can be found in
config/keybindings.cc .

  Aptitude has some support for modifiers, although it's hacky and only seems
to work reliably for Control.  However, you can (attempt to) set up
bindings for modified keys by prepending any combination of "C-", "S-", and
"A-" (or "M-") to the key.  They do the expected. :)

   Here's a quick example.  With the following binding, pressing Home, "_"
(underscore), or Control-a would execute the ListTop command.

  ListTop "home,C-a,_";

   The following commands are available for binding:

Command			Default		Effect

ExitScreen		q		Exits the current screen.
CycleScreen		tab		Switches to the next screen.  Currently
					this has no effect.

ToggleExpanded		Enter		Expands or collapses a selected tree.
SelectParent		^		Selects the parent of the current item.
SelectNext		Down		Selects the next item in a list.
SelectPrev		Up		Selects the previous item in a list.
NextPage		Pagedown	Moves to the next page of items.
PrevPage		Pageup		Moves to the previous page of items.
ListTop			Home		Moves to the top of the list.
ListBottom		End		Moves to the bottom of the list.
ListSearch		/		Searches for an item in the list.

EditDelBack		Backspace	While editing, deletes the previous
					character.
EditDone		Return		Accepts a value and terminates editing.

SelectPackage		+		Marks a package for installation, or
					cancels a "RemovePackage" command.
DeselectPackage 	-		Marks a package for removal, or cancels
					a "SelectPackage" command.
HoldPackage		=		Places a package on hold; it will be
					neither upgraded nor removed.  Can be
					used to explicitly hold an installed
					package.
PurgePackage		_		Marks a package for purging.
PackageVersions		v		Displays all known versions of a
					package.
PackageDependencies	d		Displays the dependencies of a package.
PackageDescription	i		Displays the description of a package.
PackageInfoScreen	enter		Displays lots of information about a
					package: its dependencies, its size,
					its maintainer, available versions,
					and so on.

UpdatePackageList	u		Fetches new package lists
DoInstallRun		g		Fetches packages and completes any
					pending installations/removals.

                                     COLORS

  As of version 0.0.4, Aptitude has support for configurable colors; all you
folks who've always wanted your package manager to display its output in
mauve and puce (you know who you are..) can have your wish (and good
riddance :) )

  Like the keybindings, colors are configured in a dedicated group:
Aptitude::UI::Colors.  The names of the colors are currently not in the
UpperCase-And-Hyphen style favored by apt.conf; this will probably change in
the next release (forcing everyone to update their configuration, sorry :( )

  Each color is itself a group containing just two values: the foreground
color and the background color.  These can be specified either as integers,
which are used as direct color indexes, or with a symbolic name.  There
aren't many names available (Curses' color support is fairly minimal..), but
here they are:
black
red
green
yellow
blue
magenta
cyan
white

  You place the group after the name of the color that you want to redefine.
So to define a color, include a line in the group Aptitude::UI::Colors of the
form:

  some_color {foreground; background;};

  Selected items in a list are displayed in reverse video.

  The colors available for redefinition are:
tree_header_color	 The color used to display the text in headers of trees
	default: blue,yellow
tree_background_color	 The color used to display the background of trees and
			normal, unselected items in trees.
tree_status_color	 The color used to display the status line in trees

pkg_to_hold		 The color used to display packages which are on hold
	default: black,white
pkg_to_remove		 The color used to display packages which will be
			removed
	default: black,magenta
pkg_broken		 The color used to display packages which are broken
			in some way
	default: black,red
pkg_to_install		 The color used to display packages which will be
			newly installed or reinstalled
	default: black,green
pkg_to_upgrade		 The color used to display packages which will be
			upgraded
	default: black,cyan
pkgtree_error		 The color used to display APT error messages
	default: black,red
pkgtree_progress	 The color used to display the progress bar in package
			trees (eg, the one used to show the progress being
			made in loading the package cache)
dep_broken		 The color used to display broken dependencies
	default: black,red
item_download_progress	 The color used to display download progress bars for
			individual items
	default: black,yellow
item_download_hit	 The color used to display 'hit' download messages
	default: black,green
item_download_error	 The color used to display download errors
	default: black,red
download_progress	 The color used to display the overall download
			progress bar
	default: black,yellow

  Here's a complete example of how to redefine several colors.  Inserting this
into your apt.conf will give you an incredibly ugly color scheme.  Don't say
I didn't warn you :)

Aptitude::UI::Colors {
  tree_background_color {white; magenta;};
  tree_status_color {green; cyan;};
  tree_header_color {red; yellow;};
  pkgtree_progress {cyan; white;};
};

                           OTHER CONFIGURATION OPTIONS

  (note that some standard Apt options -- the Acquire options and directory
   options in particular -- will affect aptitude's operations)

Dir::Aptitude::state
			 Aptitude now has some persistent state information;
			this directory holds that information.
	default: /var/state/aptitude

Aptitude::Track-Dselect-State
			 If this is set, Aptitude will watch the dselect state
			of a package and alter its own internal state whenever
			this changes.  You almost certainly want this to be
			on -- in fact, I'm not entirely certain that turning
			it off will work >=)  (if you care, please test
			Aptitude with this option off and let me know what
			breaks so I can fix it)
			 This was added to fix the "Aptitude and dselect fight
			over package states" bug in 0.0.3 .
	default: true

Aptitude::Auto-Upgrade
			 If this is set, packages with state "install" will be
			automatically flagged for upgrade when a new version
			is available.
	default: true

Aptitude::Fix-Broken
			 If this is set, Aptitude will attempt to resolve any
			unmet dependencies when it installs or removes
			packages.  This can result in some slight weirdness --
			packages flagged to be installed, kept, or removed as
			a result of this will only remain flagged until you
			exit the program -- but can be useful.  Fixing the
			weirdness is, I believe, closely related to undo
			support.
	default: true

Aptitude::Auto-Install
			 If this is set, Aptitude will automatically attempt to
			immediately resolve a program's dependencies when you
			mark it for installation (as opposed to waiting until
			you do an install run)
	default: false

Aptitude::Display-SizeStates
			 If this is set, Aptitude will display an estimate in
			the header of package lists of the amount to be
			downloaded in the next package run and the amount of
			space which will be used or freed.  For various
			reasons, this isn't totally accurate at the moment (for
			example, partial packages aren't accounted for); I hope
			I can fix at least some of this inaccuracy in the
			future..
	default: true

Aptitude::Forget-New-On-Update
			 If this is set, Aptitude will discard all internal
			information about which packages are "new" whenever
			it updates its package lists.
	default: false

Aptitude::Forget-New-On-Install
			 If this is set, Aptitude will discard all internal
			information about which packages are "new" whenever it
			installs and/or removes packages.

	default: false
Aptitude::Allow-ReInstall
			 If this is set, you will be able to select
			already-installed packages for installation.
	default: true

 -- Daniel Burrows <Daniel_Burrows@brown.edu>
