		       Aptitude 0.2.11.1 README
		    Copyright 2000 Daniel Burrows


			       OVERVIEW

  Aptitude is a curses-based frontend to apt, part of the Debian package
management system.

  This is the README file for the most recent stable release of
Aptitude, version 0.2.11.1.  Although this is marked "stable", aptitude is
still in a state of constant development and you may find bugs,
misfeatures, or missing features.  Please report them via
bugs.debian.org if you do.

  This file describes how to compile and use 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.

  The latest development version of aptitude is available via anonymous CVS
from sourceforge.  The CVSROOT is:

:pserver:anonymous@cvs.aptitude.sourceforge.net:/cvsroot/aptitude

  Active aptitude development is on the "ui-rewrite" branch for historical
reasons; to access it, set CVSROOT as above and run the command:

cvs checkout -rui-rewrite aptitude

			  STARTING APTITUDE

  Simply running "aptitude" with no arguments will launch the program in
interactive mode: an organized list of packages will be presented, and you
can tell the program to perform various actions on them.

  aptitude can also run in a (mostly) non-interactive mode, similar to
the popular program "apt-get".  The syntax for this is:

aptitude [options] command ...

  where "command" is the action to perform.  The following commands are
available:
  - install
             Install one or more packages.  The packages should be listed
            after the "install" command; if a package name contains a '~',
            it will be treated as a search pattern and every package
            matching the pattern will be installed.  (see "SEARCHING, etc"
            below)

             Appending "-", "+", "_", or "=" to the name of a package will
           cause the package to be removed, installed, purged, or held
           respectively.  This can be used, for instance, to perform
           multiple actions from one command line.

             As a special case, "install" with no arguments will act on
           any stored/pending actions.

             NOTE: The "install" command will modify aptitude's stored
           information about what actions to perform.  Therefore, if you
           issue the command "aptitude install foo bar" and then abort the
           installation, you will need to (eg) run "aptitude remove foo bar"
           to cancel that order.

  - remove, purge, hold
            These commands are the same as "install", but apply the
           named action to all packages unless specified otherwise.
           (for instance, "aptitude remove '~ndeity'" will remove all
            packages whose name contains "deity")

  - markauto, unmarkauto
            Mark packages as automatically installed or manually installed,
           respectively.  You may specify packages using the same syntax
           as before, including specifying actions to be performed.  For
           instance, "aptitude markauto '~slibs'" will mark all packages
           in the "libs" section as automatically installed.  See
           "TRACKING UNUSED PACKAGES" below.

  - update
            Update the list of available packages from the master servers.
           (this is equivalent to "apt-get update")

  - upgrade
            Upgrades installed packages to their most recent version.
           Installed packages will not be removed unless they are unused
           (see "TRACKING UNUSED PACKAGES" below); packages which are not
           currently installed will not be installed.
            If a package cannot be upgraded without violating these
           constraints, it will be kept back.

  - dist-upgrade
            Upgrades as many installed packages as possible to their most
           recent version.  It will install additional packages and remove
           installed packages as necessary.
            As with install, additional packages and actions may be specified
           on the command-line.  (if a package is specified without a command,
           it is assumed that the user wishes it to be installed)

  - forget-new
            Forgets all internal information about what packages are "new"
           (equivalent to pressing "f" when in interactive mode)

  - search
            Searches for packages matching one or more expressions.
           The expressions should be listed after the "search" command.
           All packages matching the given expressions will be displayed.
           As usual, this may be a full search expression; for instance,
           "aptitude search '~N'" will list all "new" packages.

  - clean
            Removes all downloaded and cached packages.

  - autoclean
            Removes any cached packages which are no longer downloadable.

  - download
            Downloads the .deb file for the most recent version of the
           given package to the current directory.

  Some command-line actions will display the following prompt if
actions you did not request are to be taken:
Do you want to continue? [Y/n/e/d/v/action/?]

  This is a miniature interface to aptitude, which you can use to adjust
the to-be-performed action, request more information, or enter the full
interactive interface.  Press "?" at this prompt for a complete description
of the available actions.

  See aptitude(1) for more information.

				USAGE

  When aptitude starts up in interactive mode, a list of packages will be
presented in a hierarchical tree.  You can navigate through the package list
using the arrow keys; the currently selected item in the list will be
highlighted.

			      Navigation

  The display is organized hierarchically.  Some items contain large groups
of packages; for instance, "Upgradable Packages" contains all the packages
which may be upgraded.  A "subitem" of an item is any item contained within
it.

  You can "open" and "close" these items to show or hide their contents.
An "open" item is one whose contents are visible; it looks like this:

--\ Installed Packages

  A "closed" item is one whose contents are hidden; it looks like this:

--- Installed Packages

  Within these groups of packages are individual packages.  They look
like this:

idA   aptitude                                            0.2.8.1-1 0.2.8.1-1

  The characters at the far left of the display tell you the current
state of the package, the proposed action, and whether it was automatically
installed.
  In this example, aptitude is currently installed, it will be deleted,
and it was automatically installed.  (since no-one will ever remove aptitude,
this is clearly an unrealistic example)

  The versions on the far right are the currently installed version, and the
'to-be-installed' version.

  To manipulate a package, move the highlight to it and then press an
action key such as '+' or '-' (described below)  Pressing an action key
on a group of packages will affect the entire group.

  See "PACKAGE DISPLAY" below for a more detailed description of the display.

			     General Keys

Control-L: redraw the screen

           The following commands allow you to navigate in the list of
           packages, and to open or close items.

Up arrow, 'k': Move up one package
Down arrow, 'j': Move down one package
Home, Ctrl-A: Move to the top of the package list.
End, Ctrl-E:  Move to the bottom of the package list.
'J': Move to the next item at the current level.  (that is, without
    moving into the selected item's contents)
'K': Move to the previous item at the current level.

Enter: Open or close an item, or view information about a package
'[': Open an item and all its subitems
']': Close a tree and all its subitems
'^' (caret): move to the item containing the selected item.

           The following commands allow you to manipulate the state of a
           package.

'+': As in dselect, mark the current package to be upgraded or installed in the
    next package run.  aptitude will automagically fill in the
    dependencies of the package unless you tell it not to (see
   "Auto-Install" in the Options section for details)

     If used on a particular version of a package, causes that version to
   be installed.

     This command should also be used to cancel "hold" actions.

'-': Mark the package to be removed
'=': Place the package on hold.
'_': Mark the package to be purged.
'L': Mark the package to be reinstalled.

'M': Mark the package as having been automatically installed. (see
    "TRACKING UNUSED PACKAGES" below)

'm': Mark the package as having been manually installed.

'I':  Mark a single package and its dependencies for installation,
    and all other packages as being kept in their current
    state.   The "hold" state of the other packages will not be
    saved for when aptitude is run in the future.  This effectively
    means that you can select a package, press 'I', perform an install
    run, and get the effect of "apt-get install PACKAGE".

'f': Forget all about which packages are 'new'.  This will cause the
    "New Packages" group, if one exists, to be merged with the rest
    of the groups.

Control-_, control-u: Undo the last action.  There is currently no "redo"
    command.  If you update the list of packages or install/remove packages,
    all undo information will be lost.

           The following commands allow you to view information
           about a package.

'i': View all information about a package.
'd': Show the dependencies of a package
'r': Show all packages which depend on a package ("r"everse dependencies)
'v': Show the available versions of a package.  (you may choose to install
    a particular version of a package if more than one is available)

'D': Display or hide the extended description area.
'a': Scroll the extended description area down (from the main display)
'z': Scroll the extended description area up   (from the main display)
'Tab': Switch focus between the main display and the extended description
      area, or move to the next entry area in a dialog box.

	   The following commands perform general actions.

'u': Update the lists of available packages.  NOTE: there appears to be a bug
    somewhere (I'm not sure where) which causes a slew of error messages when
    you abort an update run.
'g': Perform an install run.

'q': Quit the current screen, keeping all changes, and exit the program if it
    is the last screen.

'/': Search for a package (see below for information on building complex search
    terms) You can edit the string to search for using the keys listed in
    the "Editing Keys" section.  Entering a blank string will repeat the last
    search.
'\': Repeat the last search.
'R': Reconfigure the settings in the package's debconf database.
'p': Change the column formatting used to display packages
's': Change the column formatting used in the status line
  How to set column formattings is described below, under "CONFIGURATION"

'l': Change the limiting expression for the display (see below)
'G': Change the grouping policy (see below)
'S': Change the sorting policy (see below)
'?': Display the online help

			  Editing controls:

  While editing text, the following controls are available:
Up/Down: Move in the list of previous entries, if available.

Right/Left: Move right and left in the text.

Home, Ctrl-A: Move to the start of the text.

End, Ctrl-E: Move to the end of the text.

Ctrl-U: Delete all text from the cursor position to the beginning of the line.

Ctrl-K: Delete all text from the cursor position to the end of the line.

  When you are editing text in a "minibuffer" at the bottom of the screen,
the following is available:

Control-g: Cancel editing and abort whatever operation is being performed.

		       TRACKING UNUSED PACKAGES

  aptitude keeps track of which packages on your system were automatically
installed.  (ie, were installed solely to fulfill dependencies)

  When a package which was automatically installed will not be depended
upon by any manually installed package, aptitude will *automatically* mark
it to be removed.  In the preview screen, these packages will be displayed
as having been "removed because they are no longer used".
  (note: aptitude will never automatically remove an Essential package)

  For example, suppose that you want to install "coolapp", which depends
on "libcool3".  You do not have "libcool3" installed on your system, so
aptitude automatically installs it for you.  However, after installing
"coolapp", you discover that it is not that cool after all, and you want
to remove it.  When you mark "coolapp" for removal, aptitude will notice
that no package depends on "libcool3" and will automatically decide to
remove it.

  To mark a package as having been automatically installed, press "M" while
it is selected.  To remove this marking, press "m" while it is selected.

  You can tell aptitude not to automatically delete unused packages from
the Dependency Handling configuration dialog, or via Aptitude::Delete-Unused.
  In this case, you can still find out which packages were automatically
installed and are not depended upon with the seasrch term "~M~r".

  You can also create a "search term" to limit this behavior; only unused
packages which match this expression will be automatically removed.
Set this in the Dependency Handling configuration dialog, or via
Aptitude::Delete-Unused-Pattern.
  If you set it to a blank string (the default), all unused packages will
be automatically removed.

			   PACKAGE DISPLAY

  aptitude's package display is fairly customizable, although I hope
the defaults will suffice for most people.  This section describes the
default package display.

  The packages are laid out in a tree format.  The first level of the tree
divides packages according to their status on the system: whether they are
installed, not installed, obsolete, upgradable, or virtual.  The second level
divides them according to their section; for instance, games are under "games".
The third level divides them according to whether they are in main, contrib,
or non-free.

  Each package is displayed with five columns of information (there are,
by default, brief column descriptions at the top of the screen)

  The first column is a single-character "state" flag, which describes the
current state of the package.  Possible values for this flag are:

   v - virtual
   B - broken
   u - "unpacked"
   C - half-configured
   H - half-installed
   c - removed, but config-files still present (ie, not purged)
   p - the package and its config-files have been removed (purged)
   i - installed
   E - internal error (should not happen)

  The second column is a single-character "action" flag, which describes the
action you have asked the program to undertake with this package and the state
the package will be in afterwards.  Possible values are.

   h - hold
   p - purge
   d - delete (remove)
   B - broken
   i - install
   r - reinstall
   u - upgrade

  aptitude displays packages in a color-coded fashion.
The meaning of the colors 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: The package will have unmet dependencies if the
                  current operation proceeds (it is "broken")

-> Blue background: This package will be upgraded on the next run.

-> White background: This package could be upgraded, but the upgrade has
  been overridden (this is equivalent to "hold" in dselect).

-> Green background: This package will be installed on the next run.

-> Magenta background: This package will be removed on the next run.

		 SEARCHING, LIMITING, AND EXPRESSIONS

  Aptitude sports a fairly powerful system for searching for particular
packages and limiting the package display.  Users familiar with mutt will pick
up quickly, as it was the inspiration for the expression syntax.

  A search expression contains one or more "search terms" in a row.  Each
search term specifies some condition which must be true: for example, the
section of the package, or the package's installed state.  If this condition
is true, the search term is said to "match" the package.
  A search term can consist simply of a series of characters; eg, "gnome".
In this case, it will match the name of the package.
  For more complex searches, it can consist of a tilde (~) followed by a
single character describing the type of search term desired, and then possibly
a string to be matched.
  There are two types of search terms: those which match against a string,
and those which do not.  For those which do not, you simply write '~<type>'
and are done.  For example, "~b" will match any broken package.  If you are
using a search term which requires a string to be matched, you must write the
string immediately following the search type.  For example,
~mDaniel Burrows
  will match all packages which I maintain.

  Whitespace is significant within search terms, even at the beginning and
end.  In other words, "~mDaniel Burrows" and "~m Daniel Burrows" are
two different search terms, the second of which will not match anything
at all!

  To require that a search term not be matched -- that is, to describe the
opposite of a search term -- type '!' in front of it.  For example:
!~v
  will match any package which is not a pure virtual package.

  Search terms can also be grouped together.  To require every one of several
search terms to be matched (an "and" matching), write them one after another,
as so:
~b  ~snet~nhttp

  This will match any broken package in the section "net" whose name contains
"http".  You can require that any one of several search terms be true by
placing "|" between them (an "or" matching):
~b|~v

  will match any broken package or any pure virtual package.  Finally, placing
parentheses around a group of terms will cause them to be grouped into a single
meta-term.  This is useful for combining "and" and "or" in one expression.
For example:
~b(~mDaniel Burrows|~snet)
  will match any broken package which I maintain or which is in the "net"
section.

  Hopefully you now have some idea what expressions can do.  But what are they
used for?  Well, there are two places you can type an expression:
 -> When searching for a package, any expression can be entered
  (note: the current implementation is rather inefficient; the technical
        details are that the program has to recompile the search expression
        for each and every package.  Given that there are several thousand
        packages, completing in about 5 seconds on my slow system is impressive
        but still too slow.
         This only seems to be a problem for moderately complex expressions.)
 -> Expressions are used to limit the display of packages

  The second application is perhaps even more powerful than searching.  An
expression can act as a filter for the display of packages: any packages which
match the expression are displayed, any which don't are not.  The default is to
display all packages; you can type 'l' while running the program to change it,
or set the configuration option Aptitude::Pkg-Display-Limit.
  A quick example: a limit of

!(~snon-free|~scontrib)
  will hide all packages in non-free or contrib.

  To actually type ~, write "~~".

         Available types of search terms:
~a<action>
	 This will match any package which will have the given action
	performed on it.  Available actions are "install", "upgrade",
	"remove", "purge", and "hold".  Note that packages which are
	to be purged will be matched by either "purge" or "remove"; this
	is intentional.  (even if it may not be a good idea?)
~A<archive>
	 This will match any package which has a version from the given
	archive.  Archives include "stable", "unstable", and "experimental".
~b
	 This will match any broken package.
~B<type>
	 This will match any package which has an unmet dependency of the
	given type.  Available types are "depends", "predepends",
	"recommends", "suggests", and "conflicts".
~c
	 This will match any package which is removed but still has conffiles
	remaining on the system.
~C<expression>
	 This will match any package conflicting with another package which
	matches the given expression.  The expression may be an arbitrary
	search term.

	 For example, to see packages which conflict with currently
	broken packages, you would use:
	~C(~b)
~d<desc>
	 This will match any package whose description (short or long) matches
	the given string.
~D<expression>
	 This will match any package depending or pre-depending on another
	package which matches the given expression.  The expression may be
	an arbitrary search term.

	 For example, to see all packages which depend on packages I
	maintain, but which are not maintained by me, you would use:
	                  ~D(~mburrows)!~mburrows
~e
	 Not really a search term at all; this toggles "exact match" mode.
	By default, a search term will be considered to match a target string
	if the target string contains any copies of the search term; for
	example, "gv" matches "imgvtopgm".  To force the match to be exact, so
	that the two strings must be identical, place one ~e in the input
	string, before the match.  Another ~e will reset the option to the
	default value (off).
~E	 This will match any essential package.

~g
         This will match any package which is considered "unused" by the
        "unused package logic".  The "g" stands for "garbage".

~i
	 This will match any package which is installed.

~M
	 This will match any automatically installed package.

~m<name>
	 This will match any package whose Maintainer: field matches the
	given string.
~n<name>
	 This will match any package whose name matches the given string.
~N
	 This will match any "new" package.
~O<origin>
	 This will match any package which has a version from the given
	origin.  Packages in the Debian archives have an origin of "Debian",
	but if you have installed packages from other sources, they will have
	other origins.
~p<priority>
	 This will match any package whose Priority: field matches the given
	string.
~r
	 This will match any package which no installed, Essential, or
	to-be-installed package declares an "important" dependency on.
	(Depends or Recommends)

~R<type>
	 This will match any package which no installed package
	declares a dependency of the given type on.  Available types are
	"depends", "predepends", "recommends", "suggests", and "conflicts".
~s<section>
	 This will match any package whose Section: field matches the given
	string (packages without a section cannot be matched this way)
~t<task>
	 This will match any package whose Task: field matches the given
	string.  (ie, it is in the specified task)
~U
	 This will match any upgradable package.
~v
	 This will match any pure virtual package: a package which does not
	have any real version, but is only "provide"d by other packages.

~V<version>
	 This will match any package whose Version: field matches the given
	string.

                                  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! :)

  Most options are configurable from the "Options" menu in the user
interface.  When you select "Ok" in this menu, aptitude will save your
options in ~/.aptitude/config.  (be aware that this file will override the
system Aptitude configuration, even if that configuration is newer)

                                   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!

  WARNING: As of 0.0.6.9, the keybinding configuration system has changed
          significantly: keybindings are organized hierarchically, and
          the names of individual bindings are less specific (eg, Up
          instead of PagerUp)

  For people who want more control over keybindings, it's possible to override
keybindings in a particular context.  For example, maybe you want Space
to mean "move one screen forward, but only in the pager"  There are
sub-groups of the keybindings configuration group which work exactly the
same way as the configuration group itself; see below for a list of these.

  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 Begin command.

  Begin "home,C-a,_";

   The following commands are available for binding:

Command			Default		Effect

Quit			q		Closes the current view.
QuitProgram		Q		Quits the entire program.
Cycle			tab		Switches the input between "widgets"
					in the current display.
CycleNext		F6		Switches to the next available display.
CyclePrev		F7		Switches to the previous available
					display.
Refresh			C-l		Clears the screen and redraws it
					from scratch.

Help			?		Display information about the current
					screen.
Undo			C-_,C-u		Undo the last action (or group of
					actions)

ToggleExpanded		Enter		Expands or collapses a selected tree.
ExpandTree		[none]		Unconditionally expands a selected
					tree.  Has no effect on collapsed
					trees.
CollapseTree		[none]		Unconditionally collapses a selected
					tree.  Has no effect on expanded trees.
ExpandAll		[		Expands a tree and all its children.
CollapseAll		]		Collapses a tree and all its children.
Parent			^		Selects the parent of the current item.
Down			Down,j		Moves one item down: selects the next
					item in a list, or scrolls the pager
					down one line.
Up			Up,k		Moves one item up: selects the previous
					item in a list, or scrolls the pager
					up one line.
HistoryPrev		Up, C-p		Selects the previous item in the
					history of a line editor.
HistoryNext		Down, C-n	Selects the next item in the
					history of a line editor.

DescriptionUp		a		When viewing the package list, scrolls
					the description area up one line.
DescriptionDown		z		When viewing the package list, scrolls
					the description area down one line.
LevelUp			J		Moves to the previous item at the
					current level in a tree.
LevelDown		K		Moves to the next item at the current
					level in a tree.
Left			Left,l		Moves one "item" left (used by lists
					and the pager--the line editor
					overrides this to remove the binding of
					"l")
Right			Right,r		Moves one "item" right
NextPage		PageDown,C-f	Moves one page forward
PrevPage		PageUp,C-b	Moves one page backward
Begin			Home		Moves to the top of a screen.
End			End		Moves to the bottom of a screen.
Search			/		Searches for something.
ReSearch		\		Repeat the last search in the current
					screen.

Confirm			Enter		Accepts an entry while editing, or
					takes the default value in a
					multiple-choice situation.
Cancel			C-g, Escape	Cancels an action (eg, entering a
					new value in the status line)
PushButton		Space,Enter	"Pushes" a button or toggles a
					"checkbox".

DelBack			Backspace	While editing, deletes the character
					before the cursor.
DelBOL			C-u		While editing, deletes all characters
					before the cursor.
DelForward		Delete		While editing, deletes the character
					after the cursor.
DelEOL			C-k		While editing, deletes all characters
					after the cursor.

ChangePkgTreeLimit	l		Lets the user change the limit on the
					displayed list of packages.  Packages
					not matching the limit will not be
					displayed.
ChangePkgTreeGrouping	G		Lets the user change the mechanism
					used to create the package hierarchy.
ChangePkgTreeSorting	S		Lets the user edit the rules used
					to sort packages.

Install			+		Marks a package for installation.
Remove 			-		Marks a package for removal.
Hold			=		Places a package on hold; it will be
					neither upgraded nor removed.
Purge			_		Marks a package to be purged.
InstallSingle		I		Marks a particular package and all
					its dependencies for installation,
					and marks all other packages to be kept
					back.  (their sticky states will not
					be altered)  It may not be obvious
					what will happen if you don't
					immediately do an install run, but
					you can wait on that if you want :)
ReInstall		L		Marks a package for reinstallation.

SetAuto			M		Marks a package as having been
					automatically installed.
ClearAuto		m		Marks a package as having been
					manually installed.

Versions		v		Displays all known versions of a
					package.
Dependencies		d		Displays the dependencies of a package.
ReverseDependencies	r		Displays the reverse dependencies of a
					package.
Description		[none]		Displays the description of a package.
InfoScreen		Return,i	Displays lots of information about a
					package: its description, its
					dependencies, its size, its maintainer,
					available versions, and so on.
PackageChangelog	C		Downloads and displays the package's
					changelog.

DpkgReconfigure		R		Runs "dpkg-reconfigure" on the
					package.

ForgetNewPackages	f		Forgets all information about
					which packages are 'new'.

UpdatePackageList	u		Fetches new package lists
DoInstallRun		g		Fetches packages and completes any
					pending installations/removals.
ShowHideDescription	D		Shows or hides the extended description
					area in the default display layout.
EditHier		E		Opens the package hierarchy editor.
SaveHier		S		Saves the package hierarchy (when
					used from the editor)

ToggleMenuActive	C-space		Activates the menu bar.

  As mentioned above, you can use subgroups to specifically change a binding
in a particular context.  Currently available contexts are:

Pager			The internal pager
MinibufChoice		Multiple-choice prompts in the status line
MinibufEdit		The status-line editor

Tree			All tree displays
AptTree			All apt-related tree displays
PkgTree			Lists of apt packages
PkgActionTree		The "preview" tree displayed before installation
PkgNode			All things that can be operated on by the package
			status-changing commands: packages, package groups,
			versions, and dependencies.

                                     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;};

  To get bold video, add "bold" to the front of the *foreground*
color name:

  some_color {boldforeground; boldbackground;};

  Selected items in a list are displayed in reverse video.

  The colors available for redefinition are:
Error			 The color used for various error message
	default: boldwhite, red

ScreenHeaderColor	 The color used to display the screen header
	default: boldwhite, blue

ScreenBackgroundColor	 The color used to display the background of screens
	default: boldwhite, black

ScreenStatusColor	 The color used to display the status line
	default: boldwhite, blue

MenuEntry		 The color used to display items in a menu.
			A "boldface" version of this will be used for hotkeys.
	default: white, blue

MenuBorder		 The color used to draw menu borders.
	default: boldwhite, blue

HighlightedMenuEntry	 The color used to draw the currently selected
			menu entry.
	default: boldblue, white

MenuBar			 The color used to draw the menu-bar
	default: boldblue, white

HighlightedMenuBar	 The color used to draw a selected menu-bar item.
	default: boldwhite, blue

PkgToHold		 The color used to display packages which are on hold
	default: black, white

PkgToRemove		 The color used to display packages which will be
			removed
	default: black, magenta

PkgBroken		 The color used to display packages which are broken
			in some way
	default: black, red

PkgToInstall		 The color used to display packages which will be
			newly installed or reinstalled
	default: black, green

PkgToUpgrade		 The color used to display packages which will be
			upgraded
	default: black, cyan

Progress		 The color used to display progress bars in package
			trees (eg, the one used to show the progress being
			made in loading the package cache)
	default: blue, yellow

DepBroken		 The color used to display broken dependencies
	default: black, red

DownloadProgress	 The color used to display download progress bars.
	default: black, yellow

DownloadHit	 	 The color used to display 'hit' download messages
	default: black, green

MediaChange		 The color used to display messages asking the user
			to insert a new CD.
	default: boldyellow, red

MineFlagColor		 The color used to display flags in the Minesweeper
			game.
	default: boldred, black

MineBombColor		 The color used to display bombs in the Minesweeper
			game.
	default: boldred, black

MineDetonatedColor	 The color used to display detonated bombs in the
			Minesweeper game.
	default: cyan, black



  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 {
  screen_background_color {white; magenta;};
  screen_status_color {green; cyan;};
  screen_header_color {red; yellow;};
  pkgtree_progress {cyan; white;};
};

				    COLUMNS
  As of version 0.0.5, package information is formatted into columns.  The
contents and placement of these columns are configurable by the user.

  The general layout of a column definition is a printf-style string, as
follows:
ColumnDef "Package %p, %C#%v";

  The value of ColumnDef is used as a template for generating the output.
It is literally copied into the display, but %-escapes (like "%p" above) are
replaced with special values depending on the package.  For example, "%p"
is replaced by the package's name (see below for a table of all available
%-escapes)

  The resulting output will be formatted so that identical pieces of
information are above one another; for example, in the sample above, the
package names will be printed in a vertical column.  The width of columns
generated by %-escapes is automatically selected by default, but you can
specify it manually by including a number between the "%" and the format
character.  For instance:
  %5p

  creates a 5-character (ie, too short) column containing package names.

  The pound sign (or ocalthorpe) in deserves special mention.  When more
space is allocated for a column than it can minimally use, the column might
be expanded.  A pound sign will cause the previous column to be expanded
to fill available space.  If the column does not have enough text to fill
the space, it will be padded with blanks (" ").  The %p, %d, and %m escapes
will expand by default.

  Currently, three configurable column formats are available.  These
may be modified from the "UI Options" menu.
Aptitude::UI::Package-Display-Format	This format is used to display packages
					and versions of packages.

Aptitude::UI::Package-Status-Format	This format is used in the
					status line.

Aptitude::UI::Package-Header-Format	This format is used to display
					the "header line" at the top
					of the screen.

  The same %-escapes are available in each format:
%a			A single letter describing what will be done with the
			package	in the next run. (for example, "i" for install)

%A			A more verbose description of the action which will
			be taken with the package.

%c			A single letter describing the package's current state
			(eg, "p" for purge)
			"c" stands for "CurrentState"

%C			A more verbose description of the package's current
			state.

%d			The package's short description.

%D			The size of the package in .deb format

%I			The amount of space this package will require when
			installed

%m			The package's maintainer

%M			A single letter indicating whether the package
			was automatically installed ("A" if it was, blank
			otherwise)

%p			The package or version's name.  This will be displayed
                        appropriately for the package's location in the tree
                        hierarchy.  (ie, it will be indented if it occurs too
                        close to the left-hand side of the screen)

%P			The package's priority

%R			The package's priority, in a short (3-letter)
			abbreviated form.  (r for pRiority.  Ok, that sucks..)

%s			The package's section

%v			The currently installed version of the package.


%V			The version which will be installed

 The following escapes do not change depending on what package is
selected.

%B			The number of packages which are broken

%H			The hostname of the machine Aptitude is running on.

%N			The name of the program

%n			The version number of the program

%o			The total estimated download size.  (does not
			take partially downloaded files into account)

%u			The estimated change in disk usage.


			     GROUPING CONFIGURATION

  It is possible to configure the package hierarchy which is displayed
to the user.  This is done by defining a policy that aptitude uses to
group packages together (henceforth referred to, arbitrarily, as a
"grouping policy") Grouping policies define multiple levels of
hierarchy into which packages are organized; for instance, you can
decide to have packages with the same section grouped together, and to
have subgroups composed of packages whose names start with the same
letter.

  To define a grouping policy, use a string like this:
POLICY1,POLICY2,POLICY3,...,POLICYN

  Each "POLICYX" should be the name of the policy for a particular level
(see below for a list of policies), and a list of options for that
policy:

POLICYNAME(OPTION1,OPTION2,...,OPTIONN)

  The list of options can be omitted if there are none.  Here are some
examples of how to describe a single policy:

"versions"
"section(topdir,passthrough)"
"section(subdir)"
"filter(missing)"

  The policies available are:

section(MODE,PASSTHROUGH)

  Groups packages based on the value of their "Section"
tag.  The "Section" tag traditionally consists of two parts
(eg, "contrib/lyx") and packages can be grouped based on either
the first half of the tag, the second half of the tag, or the
entire tag.  (in addition, special trees for unknown packages,
virtual packages, and task packages are created)

  MODE determines how the packages are grouped.  It may be "topdir",
"subdir", or "none" to group by the first half of the tag, the
second half of the tag, or the full tag respectively.  The default
if MODE is not provided is "none".

  PASSTHROUGH must be either "passthrough" or "nopassthrough".  If it
is provided and equal to "passthrough", packages which might
otherwise result in duplicated pieces of hierarchy will not be
placed in subtrees.  This may cause bad behavior if you don't know
what you're doing!

priority

  Groups packages based on their priority.

status

  Groups packages into the following categories:
    Installed
    Not Installed
    Obsolete
    Upgradable
    Virtual

action

  Groups packages into categories based on what the program will do on
them.  This is what is used for generating previews of what install
runs will do and is provided at the moment only for completeness.

filter

  "filter(missing)" will eliminate packages which have no available
versions, are not installed, and not provided by any other package.
This will probably be folded into the limit system in the future.

firstchar

  Groups packages based on the first character of their name.

  The following policies are special in that they do not create a new
level of hierarchy; instead, they terminate the hierarchy and create a
special form of a displayed package.

versions

  Creates packages with their available versions displayed as
sub-items.  NOTE: both this grouping method and the following one may
cause the tree-structure to get a little strange.

deps

  Creates packages with their (immediate) versions displayed as
sub-items.

  To set the default grouping policy, change Aptitude::UI::Default-Grouping.
To set the grouping policy for the current tree, press 'G'.

task

  Creates a subtree called "Tasks" containing task packages and their
contents.  The policy following this will be instantiated at the same level.

hier

  Groups packages according to a "package hierarchy" defined in an external
file.  This is meant to be a replacement for the Section-based grouping, which
is insufficient for today's Debian archive.  However, it is not currently
recommended that you use this as your primary grouping mechanism; to
make use of it, choose "New Categorical Browser" from the "Views" menu.

                             SORTING CONFIGURATION

  The method by which packages are sorted is now configurable.
Packages can be sorted using several methods; if the first method is
inconclusive, the second will be used.  (for instance, you could sort
by installed-size, then by name; packages with the same installed-size
would be sorted by name)

  Note that this is different from how packages are grouped, in that
it affects the order in which packages in the same group are displayed
rather than which group packages are displayed in.

  Sorting policy definitions have the following form:

[~]METHOD1,[~]METHOD2,...

  Each METHOD is a particular way of sorting packages (see below).
Placing a "~" in front of a method name makes it sort in reverse
order.  (so, for instance, "~name" will sort in reverse order by name)

  Only a small number of sorting methods are available now.
  Suggestions are welcome. :-)

  Available sorting methods are:

name

  Sorts packages by name.

installsize

  Sorts packages by their size when installed.

priority

  Sorts packages by their priority.

                                    THEMES

  A "theme" is a set of default configuration options for aptitude.  To select
a theme, add the line:
Aptitude::Theme "theme-name";

  to ~/.aptitude/config or /etc/apt/apt.conf .  It is important to realize
that this will only affect the default settings for options -- if you have
modified your settings from the user interface, this may not have the expected
effect.

  Aside from the default theme, the following themes are available:

Vertical-Split
  A theme designed for wide displays or xterms.  (eg, 120-160 characters or
more) It shows the package hierarchy on the left-hand side of the screen,
with the description on the right-hand side.

Dselect
  Makes aptitude look and behave more like dselect, for people who like that.


  Technical details:
Themes are stored under "Aptitude::UI::Themes::<theme name>", and
have the same structure as the entire apt.conf hierarchy (so yes, they can
set any options they want)  See /usr/share/aptitude/aptitude-defaults for
some examples of themes.

                           OTHER CONFIGURATION OPTIONS

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

  Many of these options can be modified while the program is running
from the Options menu.

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

Aptitude::AutoClean-After-Update
			 If this is set, package files which can no longer
			be downloaded (ie, have been removed from the
			archive) will be automatically removed after new
			package lists are downloaded.  Such files are usually
			old versions of packages and are usually useless.

			 You can manually delete such files at any time;
			this just provides an automatic mechanism for doing it.
	default: false

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: true

Aptitude::Auto-Fix-Broken
			 If this is false, Aptitude will prompt before fixing
			broken packages.  I do not think that turning
			this off is a good idea.
	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::Changelog-URL-Template
			 A template describing the URL which should be used to
			fetch package changelogs (this will need to be updated
			if the Debian changelog CGI script moves)
			 Place "%s" in the template where the package name
			should go.
	default: "http://cgi.debian.org/cgi-bin/get-changelog?package=%s"

Aptitude::CmdLine::Always-Prompt
			 Equivalent to "-P"
	default: false

Aptitude::CmdLine::Assume-Yes
			 Equivalent to "-y"
	default: false

Aptitude::CmdLine::Download-Only
			 Equivalent to "-d"
	default: false

Aptitude::CmdLine::Fix-Broken
			 Equivalent to "-f"
	default: false

Aptitude::CmdLine::Package-Display-Format
			 If set, aptitude will use the given string as the
			default for the "search" command's output.
	default: "%c%a%M %p# - %d#"

Aptitude::CmdLine::Package-Display-Width
			 If set (and non-empty), aptitude will use the
			given value as the default width to format the
			"search" command's output for.
	default: ""

Aptitude::CmdLine::Show-Deps
			 Equivalent to "-D"
	default: false

Aptitude::CmdLine::Show-Versions
			 Equivalent to "-V"
	default: false

Aptitude::CmdLine::Simulate
			 Equivalent to "-s"

	default: false

Aptitude::CmdLine::Verbose
			 The default verbosity level.
	default: 0

Aptitude::Column-Headers
			 If this is true, the header for the main package
			lists will display short descriptions of each column
			instead of the program name and a size estimate.
	default: true

Aptitude::Delete-Unused
			 If this is true, unused packages will be
			automatically deleted.
	default: true

Aptitude::Delete-Unused-Pattern
			 If Delete-Unused is true and this pattern is not
			an empty string, only unused packages which match
			this pattern will be automatically deleted.
			(otherwise, all unused packages will be automatically
			deleted)
	default: ""

Aptitude::Display-Planned-Action
			 If this is true, Aptitude will display a screen before
			downloading and installing packages which shows the
			actions which are about to be performed and allows you
			to optionally edit them.  (press the install key
			(generally "g") again to continue)
	default: true

Aptitude::Display-SizeStats
			 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::Log
	default: unset
			 If this is set, Aptitude will log its actions when
			installing, upgrading, or removing packages.
			  Simply setting this to a filename will cause output
			to be logged to that file.  The log can be piped into
			a command by setting the first character to a pipe
			symbol ("|") and the remainder to the command; for
			instance: "|mail -s 'Aptitude install run' root"

Aptitude::Minibuf-Download-Widget
			 aptitude 0.0.6 introduced a second interface for
			downloading files, which runs in the minibuf and is
			less obtrusive than the full-screen one.  Normally it's
			only used to download ChangeLogs; set this option to
			use it for everything.  (note: pressing "q" will
			abort a download in the minibuf widget as well as in
			the normal download screen)  (note2: that is
			broken at the moment, but it ought to work that way)
	default: false

Aptitude::Pkg-Display-Limit
			 The limit applied to packages being inserted into the
			display (empty for no limit)
	default: ""

Aptitude::Prompt-On-Exit
			 If this is true, aptitude will display a prompt before
			exiting (to avoid a common error of hitting too many
			'q's)

Aptitude::Recommends-Important
	default: true
Aptitude::Suggests-Important
	default: false
			 These state whether Aptitude will honor Recommends and
			Suggests fields by treating packages listed in
			these fields as strict dependencies.  If one of these
			is set to true, Aptitude will honor the field when
			installing a package for the first time (as opposed to
			upgrading)

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::UI::Advance-On-Action
			 If this is set, the selection will automatically
			advance to the next item at the current hierarchy
			level when you perform a state-changing action
			(such as installing, removing, or purging a package)
			The selection will never advance into or out of
			a subtree in this way.
	default: false

Aptitude::UI::Default-Grouping
			 Sets the default grouping method for package views.
	default: filter(missing),status,section(subdir,passthrough),section(topdir)

Aptitude::UI::Description-Visible-By-Default
			 If this is set, the extended description area
			will be visible by default in appropriate
			screens (eg, the package list)
	default: true

Aptitude::UI::Exit-On-Last-Close
			 If this is set, aptitude will exit when the last
			active view is closed; otherwise, it will wait for
			you to ask it to exit.
	default: true

Aptitude::UI::Package-Display-Format
			 The column format string for packages.
	default:
	  "%c%a #%p #%v%V"

Aptitude::UI::Package-Status-Format
			 The column format string for the status line
			while a package is highlighted
	default: "%d"

Aptitude::UI::Package-Header-Format
			 The column format string for the header line
			(also while a package is highlighted)
	default: "%N %n #%B %u %o"

Aptitude::UI::Pause-After-Download
			 If true, the program will pause after downloading
			files, and you will be given the option to continue
			or cancel, if applicable.
	default: true

Aptitude::UI::New-Package-Commands
			 If true, the package commands will use their
			"new" versions, in which all commands have a
			predictable behavior (in the old system, a given
			keystroke would perform different actions depending
			on the state of the package)
			 If false, use the old system.
	default: true

Aptitude::Warn-Not-Root
			 If this is set to true, Aptitude will warn you
			when you attempt to update the package lists or
			install packages as a user other than root.  You
			will be given an opportunity to run aptitude as
			root with your current package selections intact;
			doing so will of course require you to type the
			root password.
	default: true

                         EDITING PACKAGE HIERARCHIES

  To aid in the creation of auxillary package hierarchies, aptitude provides
a built-in editor for them.  To use the editor, select a package you wish
to edit and press "E".  The package-hierarchy editor will appear, listing
the available package categories.  A package may be placed into as many
categories as you wish (although this should obviously be done only in
relatively rare cases); pressing Enter while a category is selected (or
right-clicking the category with the mouse) will place it into the category
or remove it from the category.
  Pressing "q" while in the editor will hide it and store the selections
for the current package; pressing "N" will store the selections for the
current package and advance the package tree to the next item.  NOTE: if you
do not press "q" or "N", and switch to another package in some other way,
changes you have made to the current package will be discarded!

  You can save changes to the hierarchy by pressing "S".  They will be saved
in the file ~/.aptitude/function_hier.  The hierarchy information can be
sensibly patched with diff(1).

  The program dump_pkg_hier, found in src/generic, lets you visualize package
hierarchies without using aptitude.  It's also a useful debugging tool and
a good simple example of using the generic pkg_hier implementation.

 -- Daniel Burrows <dburrows@debian.org>
