path: root/doc/en/aptitude.xml

<?xml version="1.0" standalone="no"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [
  <!ENTITY aptitude "<command>aptitude</command>">
  <!ENTITY apt '<systemitem class="library">apt</systemitem>'>
  <!ENTITY dselect '<command>dselect</command>'>
  <!ENTITY apt-get '<command>apt-get</command>'>
  <!ENTITY root '<systemitem class="username">root</systemitem>'>
  <!ENTITY VERSION '0.6.8'>

  <!-- Shortcuts for menu commands: -->

  <!ENTITY actions-install "<menuchoice><shortcut><keycap>g</keycap></shortcut><guimenu>Actions</guimenu><guimenuitem>Install/remove packages</guimenuitem></menuchoice>">
  <!ENTITY actions-update "<menuchoice><shortcut><keycap>u</keycap></shortcut><guimenu>Actions</guimenu><guimenuitem>Update package list</guimenuitem></menuchoice>">
  <!ENTITY actions-cancel "<menuchoice><guimenu>Actions</guimenu><guimenuitem>Cancel pending actions</guimenuitem></menuchoice>">
  <!ENTITY actions-forget "<menuchoice><shortcut><keycap>f</keycap></shortcut><guimenu>Actions</guimenu><guimenuitem>Forget new packages</guimenuitem></menuchoice>">
  <!ENTITY actions-clean "<menuchoice><guimenu>Actions</guimenu><guimenuitem>Clean package cache</guimenuitem></menuchoice>">
  <!ENTITY actions-clean-obs "<menuchoice><guimenu>Actions</guimenu><guimenuitem>Clean obsolete files</guimenuitem></menuchoice>">
  <!ENTITY actions-upgrade "<menuchoice><shortcut><keycap>U</keycap></shortcut><guimenu>Actions</guimenu><guimenuitem>Mark Upgradable</guimenuitem></menuchoice>">
  <!ENTITY actions-mine "<menuchoice><guimenu>Actions</guimenu><guimenuitem>Play Minesweeper</guimenuitem></menuchoice>">
  <!ENTITY actions-su "<menuchoice><guimenu>Actions</guimenu><guimenuitem>Become root</guimenuitem></menuchoice>">
  <!ENTITY actions-quit "<menuchoice><shortcut><keycap>Q</keycap></shortcut><guimenu>Actions</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>">

  <!ENTITY undo-undo "<menuchoice><shortcut><keycombo action='simul'><keycap>Control</keycap><keycap>u</keycap></keycombo></shortcut><guimenu>Undo</guimenu><guimenuitem>Undo</guimenuitem></menuchoice>">

  <!ENTITY package-install "<menuchoice><shortcut><keycap>+</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Install</guimenuitem></menuchoice>">
  <!ENTITY package-remove "<menuchoice><shortcut><keycap>-</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Remove</guimenuitem></menuchoice>">
  <!ENTITY package-purge "<menuchoice><shortcut><keycap>_</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Purge</guimenuitem></menuchoice>">
  <!ENTITY package-keep "<menuchoice><shortcut><keycap>:</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Keep</guimenuitem></menuchoice>">
  <!ENTITY package-hold "<menuchoice><shortcut><keycap>=</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Hold</guimenuitem></menuchoice>">
  <!ENTITY package-markauto "<menuchoice><shortcut><keycap>M</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Mark Auto</guimenuitem></menuchoice>">
  <!ENTITY package-markmanual "<menuchoice><shortcut><keycap>m</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Mark Manual</guimenuitem></menuchoice>">
  <!ENTITY package-forbid "<menuchoice><shortcut><keycap>F</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Forbid Version</guimenuitem></menuchoice>">
  <!ENTITY package-information "<menuchoice><shortcut><keycap>enter</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Information</guimenuitem></menuchoice>">
  <!ENTITY package-cycle-information "<menuchoice><shortcut><keycap>i</keycap></shortcut><guimenu>Package</guimenu><guimenuitem>Cycle 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>&lt;</keycap></shortcut><guimenu>Resolver</guimenu><guimenuitem>First Solution</guimenuitem></menuchoice>">
  <!ENTITY resolver-last "<menuchoice><shortcut><keycap>&gt;</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 resolver-reject-break-holds "<menuchoice><guimenu>Resolver</guimenu><guimenuitem>Reject Breaking Holds</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>">
  <!ENTITY search-repeat-find-back "<menuchoice><shortcut><keycap>N</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Find Again Backwards</guimenuitem></menuchoice>">
  <!ENTITY search-limit "<menuchoice><shortcut><keycap>l</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Limit Display</guimenuitem></menuchoice>">
  <!ENTITY search-unlimit "<menuchoice><guimenu>Search</guimenu><guimenuitem>Un-Limit Display</guimenuitem></menuchoice>">
  <!ENTITY search-find-broken "<menuchoice><shortcut><keycap>b</keycap></shortcut><guimenu>Search</guimenu><guimenuitem>Find Broken</guimenuitem></menuchoice>">

  <!ENTITY options-preferences "<menuchoice><guimenu>Options</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>">
  <!ENTITY options-revert "<menuchoice><guimenu>Options</guimenu><guimenuitem>Revert options</guimenuitem></menuchoice>">

  <!ENTITY views-next "<menuchoice><shortcut><keycap>F6</keycap></shortcut><guimenu>Views</guimenu><guimenuitem>Next</guimenuitem></menuchoice>">
  <!ENTITY views-prev "<menuchoice><shortcut><keycap>F7</keycap></shortcut><guimenu>Views</guimenu><guimenuitem>Prev</guimenuitem></menuchoice>">
  <!ENTITY views-close "<menuchoice><shortcut><keycap>q</keycap></shortcut><guimenu>Views</guimenu><guimenuitem>Close</guimenuitem></menuchoice>">

  <!ENTITY views-new "<menuchoice><guimenu>Views</guimenu><guimenuitem>New Package View</guimenuitem></menuchoice>">
  <!ENTITY views-audit "<menuchoice><guimenu>Views</guimenu><guimenuitem>Audit Recommendations</guimenuitem></menuchoice>">
  <!ENTITY views-flat "<menuchoice><guimenu>Views</guimenu><guimenuitem>New Flat Package List</guimenuitem></menuchoice>">
  <!ENTITY views-debtags "<menuchoice><guimenu>Views</guimenu><guimenuitem>New Debtags Browser</guimenuitem></menuchoice>">
  <!ENTITY views-browse "<menuchoice><guimenu>Views</guimenu><guimenuitem>New Categorical Browser</guimenuitem></menuchoice>">

  <!ENTITY help-about "<menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice>">
  <!ENTITY help-help "<menuchoice><shortcut><keycap>?</keycap></shortcut><guimenu>Help</guimenu><guimenuitem>Help</guimenuitem></menuchoice>">
  <!ENTITY help-manual "<menuchoice><guimenu>Help</guimenu><guimenuitem>User's Manual</guimenuitem></menuchoice>">
  <!ENTITY help-faq "<menuchoice><guimenu>Help</guimenu><guimenuitem>FAQ</guimenuitem></menuchoice>">
  <!ENTITY help-changelog "<menuchoice><guimenu>Help</guimenu><guimenuitem>ChangeLog</guimenuitem></menuchoice>">
  <!ENTITY help-license "<menuchoice><guimenu>Help</guimenu><guimenuitem>License</guimenuitem></menuchoice>">


  <!-- By convention, the entity &Sterm; generates ?term with a link
       to the documentation of ?term. -->
  <!ENTITY Sequal "<literal><link linkend='searchEqual'>?=</link></literal>">
  <!ENTITY Snot "<literal><link linkend='searchNot'>?not</link></literal>">
  <!ENTITY Sand "<literal><link linkend='searchAnd'>?and</link></literal>">
  <!ENTITY Sor "<literal><link linkend='searchOr'>?or</link></literal>">
  <!ENTITY Saction "<literal><link linkend='searchAction'>?action</link></literal>">
  <!ENTITY Sall-versions "<literal><link linkend='searchAllVersions'>?all-versions</link></literal>">
  <!ENTITY Sany-version "<literal><link linkend='searchAnyVersion'>?any-version</link></literal>">
  <!ENTITY Sarchitecture "<literal><link linkend='searchArchitecture'>?architecture</link></literal>">
  <!ENTITY Sarchive "<literal><link linkend='searchArchive'>?archive</link></literal>">
  <!ENTITY Sautomatic "<literal><link linkend='searchAutomatic'>?automatic</link></literal>">
  <!ENTITY Sbind "<literal><link linkend='searchBind'>?bind</link></literal>">
  <!ENTITY Sbroken "<literal><link linkend='searchBroken'>?broken</link></literal>">
  <!ENTITY Sbroken-type "<literal><link linkend='searchBrokenType'>?broken-<replaceable>depType</replaceable></link></literal>">
  <!ENTITY Sbroken-type-term "<literal><link linkend='searchBrokenTypeTerm'>?broken-<replaceable>depType</replaceable></link></literal>">
  <!ENTITY Sbroken-reverse-dep "<literal><link linkend='searchReverseBrokenDep'>?broken-reverse-<replaceable>depType</replaceable></link></literal>">
  <!ENTITY Sconflicts "<literal><link linkend='searchConflicts'>?conflicts</link></literal>">
  <!ENTITY Sconfig-files "<literal><link linkend='searchConfigFiles'>?config-files</link></literal>">
  <!ENTITY Sdep "<literal><link linkend='searchDep'>?<replaceable>depType</replaceable></link></literal>">

  <!ENTITY Sdepends "<literal><link linkend='searchDep'>?depends</link></literal>">
  <!ENTITY Srecommends "<literal><link linkend='searchDep'>?recommends</link></literal>">
  <!ENTITY Ssuggests "<literal><link linkend='searchDep'>?suggests</link></literal>">

  <!ENTITY Sdescription "<literal><link linkend='searchDescription'>?description</link></literal>">
  <!ENTITY Sessential "<literal><link linkend='searchEssential'>?essential</link></literal>">
  <!ENTITY Sexact-name "<literal><link linkend='searchExactName'>?exact-name</link></literal>">
  <!ENTITY Sfalse "<literal><link linkend='searchFalse'>?false</link></literal>">
  <!ENTITY Sfor "<literal><link linkend='searchFor'>?for</link></literal>">
  <!ENTITY Sgarbage "<literal><link linkend='searchGarbage'>?garbage</link></literal>">
  <!ENTITY Sinstalled "<literal><link linkend='searchInstalled'>?installed</link></literal>">
  <!ENTITY Smaintainer "<literal><link linkend='searchMaintainer'>?maintainer</link></literal>">
  <!ENTITY Smultiarch "<literal><link linkend='searchMultiArch'>?multiarch</link></literal>">
  <!ENTITY Snarrow "<literal><link linkend='searchNarrow'>?narrow</link></literal>">
  <!ENTITY Sname "<literal><link linkend='searchTermName'>?name</link></literal>">
  <!ENTITY Snew "<literal><link linkend='searchNew'>?new</link></literal>">
  <!ENTITY Sobsolete "<literal><link linkend='searchObsolete'>?obsolete</link></literal>">
  <!ENTITY Sorigin "<literal><link linkend='searchOrigin'>?origin</link></literal>">
  <!ENTITY Sprovides "<literal><link linkend='searchProvides'>?provides</link></literal>">
  <!ENTITY Spriority "<literal><link linkend='searchPriority'>?priority</link></literal>">
  <!ENTITY Sreverse-dep "<literal><link linkend='searchReverseDep'>?reverse-<replaceable>depType</replaceable></link></literal>">

  <!ENTITY Sreverse-depends "<literal><link linkend='searchReverseDep'>?reverse-depends</link></literal>">
  <!ENTITY Sreverse-recommends "<literal><link linkend='searchReverseDep'>?reverse-recommends</link></literal>">
  <!ENTITY Sreverse-suggests "<literal><link linkend='searchReverseDep'>?reverse-suggests</link></literal>">

  <!ENTITY Sreverse-broken-dep "<literal><link linkend='searchReverseBrokenDep'>?reverse-broken-<replaceable>depType</replaceable></link></literal>">
  <!ENTITY Ssection "<literal><link linkend='searchSection'>?section</link></literal>">
  <!ENTITY Ssource-package "<literal><link linkend='searchSourcePackage'>?source-package</link></literal>">
  <!ENTITY Ssource-version "<literal><link linkend='searchSourceVersion'>?source-version</link></literal>">
  <!ENTITY Stag "<literal><link linkend='searchTag'>?tag</link></literal>">
  <!ENTITY Sterm "<literal><link linkend='searchTerm'>?term</link></literal>">
  <!ENTITY Sterm-prefix "<literal><link linkend='searchTermPrefix'>?term-prefix</link></literal>">
  <!ENTITY Strue "<literal><link linkend='searchTrue'>?true</link></literal>">
  <!ENTITY Stask "<literal><link linkend='searchTask'>?task</link></literal>">
  <!ENTITY Supgradable "<literal><link linkend='searchUpgradable'>?upgradable</link></literal>">
  <!ENTITY Suser-tag "<literal><link linkend='searchUserTag'>?user-tag</link></literal>">
  <!ENTITY Sversion "<literal><link linkend='searchTermVersion'>?version</link></literal>">
  <!ENTITY Svirtual "<literal><link linkend='searchVirtual'>?virtual</link></literal>">
  <!ENTITY Swiden "<literal><link linkend='searchWiden'>?widen</link></literal>">


  <!ENTITY manpage SYSTEM "manpage.xml">
]>

<book lang="en"> <bookinfo> <title>&aptitude; user's manual</title>
<subtitle>Version &VERSION;</subtitle>

<author><personname><firstname>Daniel</firstname><surname>Burrows</surname></personname><email>dburrows@debian.org</email></author>

<copyright>
  <year>2004-2008</year>
  <holder>Daniel Burrows</holder>
</copyright>

<legalnotice>
  <para>
    This manual is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation; either version 2 of the
    License, or (at your option) any later version.
  </para>

  <para>
    This manual is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.
  </para>

  <para>
    You should have received a copy of the GNU General Public License
    along with this manual; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    02111-1307 USA
  </para>
</legalnotice>

</bookinfo>

<toc/>

<preface>

  <title>Introduction</title>

  <blockquote>
    <attribution>
      <personname>
	<firstname>John</firstname>
	<surname>Fouhy</surname>
      </personname>
    </attribution>

    <para>
      <quote>Master, does Emacs possess the Buddha nature?</quote> the
      novice asked.
    </para>

    <para>
      <quote>I don't see why not,</quote> replied the master.
      <quote>It's got bloody well everything else.</quote> Several
      years later, the novice suddenly achieved enlightenment.
    </para>
  </blockquote>

  <para>
    Hello, and welcome to the &aptitude; user's manual!  This
    introductory section explains what &aptitude; is and how to get
    your hands on it; for information on actually using it, please
    proceed to <xref linkend='chapGettingStarted'/>.
  </para>

  <section>

    <title>What is this aptitude thing, anyway?</title>

    <para>
      &aptitude; is a featureful package manager for Debian GNU/Linux
      systems, based on the renowned &apt; package management
      infrastructure.  &aptitude; provides the functionality of
      &dselect; and &apt-get;, as well as many additional features not
      found in either program.
    </para>

  </section>

  <section>

    <title>What is a package manager?</title>

    <para>
      A <firstterm>package manager</firstterm> keeps track of what
      software is installed on your computer, and allows you to easily
      install new software, upgrade software to newer versions, or
      remove software that you previously installed.  As the name
      suggests, package managers deal with
      <firstterm>packages</firstterm>: collections of files that are
      bundled together and can be installed and removed as a group.
    </para>

    <para>
      Often, a package is just a particular program.  For instance,
      the instant messaging client <command>gaim</command> is
      contained in the Debian package of the same name.  On the other
      hand, it is common for programs to consist of several
      interrelated packages.  For instance, the
      <command>gimp</command> image editor consists not only of the
      <systemitem>gimp</systemitem> package, but also of the
      <systemitem>gimp-data</systemitem> package; in addition, several
      optional add-on packages (containing esoteric data,
      documentation, and so on) are also available.  It is also
      possible for several small, related programs to be contained in
      a single package: for instance, the
      <systemitem>fileutils</systemitem> package contains several
      common Unix commands, such as <command>ls</command>,
      <command>cp</command>, etc.
    </para>

    <para>
      Some packages require other packages in order to function.  In
      Debian, packages can <firstterm>depend</firstterm> upon,
      <firstterm>recommend</firstterm>,
      <firstterm>suggest</firstterm>,
      <firstterm>break</firstterm>, or
      <firstterm>conflict</firstterm> with other packages.
    </para>

    <itemizedlist>

      <listitem>
	<para>
	  If a package A depends upon another package B, then B is
	  required for A to operate properly.  For instance, the
	  <systemitem>gimp</systemitem> package depends upon the
	  <systemitem>gimp-data</systemitem> package in order to
	  ensure that the <ulink
	  url='http://www.gimp.org'>GIMP</ulink> graphics editor can
	  access its critical data files.
	</para>
      </listitem>

      <listitem>
	<para>
	  If a package A recommends another package B, then B provides
	  important additional functionality to A that will be desired
	  in most circumstances.  For instance, the
	  <systemitem>mozilla-browser</systemitem> package recommends
	  the <systemitem>mozilla-psm</systemitem> package, which adds
	  support for secure data transfers to the <ulink
	  url='http://www.mozilla.org'>Mozilla</ulink> Web browser.
	  While <systemitem>mozilla-psm</systemitem> is not strictly
	  required for Mozilla to function, most users will want
	  Mozilla to support the secure transmission of confidential
	  data (such as credit card numbers).
	</para>
      </listitem>

      <listitem>
	<para>
	  If a package A suggests another package B, then package B
	  provides functionality that may enhance A, but is not needed
	  in most cases.  For instance, the
	  <systemitem>kmail</systemitem> package suggests the
	  <systemitem>gnupg</systemitem> package, which contains
	  encryption software that can be used by <ulink
	  url='http://kmail.kde.org/'>KMail</ulink>.
	</para>
      </listitem>

      <listitem>
	<para>
	  If a package A conflicts with another package B, then the
	  two packages cannot be installed at the same time.  For
	  instance, <systemitem>fb-music-hi</systemitem> conflicts
	  with <systemitem>fb-music-low</systemitem> because they
	  provide alternate sets of music for the game <ulink
	  url='http://www.frozen-bubble.org'>Frozen Bubble</ulink>.
	</para>
      </listitem>
    </itemizedlist>

    <para>
      The job of a package manager is to present an interface which
      assists the user in managing the collection of packages
      installed on his or her system.  &aptitude; provides such an
      interface by building on the &apt; package management system.
    </para>

    </section>

    <section>
      <title>What is the &apt; system?</title>

      <para>
	Being able to install and remove packages is great, but the
	basic software for doing this (known as
	<systemitem>dpkg</systemitem>) does exactly that and nothing
	more.  This is fine if you download one or two packages by
	hand, but quickly becomes cumbersome when you are trying to
	manage a large number of packages.  Furthermore, if your shiny
	new package requires software you haven't yet installed, you
	have to download the newly required software by hand.  And if
	you later decide to remove the no-longer-shiny package, these
	extra packages will linger on your system, consuming hard
	drive space, unless you manually remove them.
      </para>

      <para>
	Obviously, all of this manual labor is a tedious chore, and so
	most package management systems come with software which takes
	care of some or all of it for you.  &apt; is a common base on
	which to build these programs: in addition to &aptitude;,
	programs such as <command>synaptic</command> and
	<command>apt-watch</command> make use of &apt;.
      </para>

      <para>
	&apt; works by keeping a list of the packages that can be
	downloaded from Debian on your computer.  This list is used to
	find packages that need to be upgraded and to install new
	packages.  &apt; can also solve many dependency problems
	automatically: for instance, when you choose to install a
	package, it will find any additional required packages and
	install those as well.
      </para>

      <para>
	When working with a package manager based on &apt;, such as
	&aptitude;, you will typically perform three basic tasks: you
	will <firstterm>update</firstterm> the list of packages that
	are available by downloading new lists from the Debian
	servers, you will <firstterm>select</firstterm> which packages
	should be installed, upgraded, or removed, and finally, you
	will <firstterm>commit</firstterm> your selections by actually
	performing the installations, removals, etc.
      </para>

      <para>
	&apt;-based package managers read the list of <quote>sources</quote> --
	repositories of Debian packages -- from the file
	<filename>/etc/apt/sources.list</filename>.  The format and
	contents of this file are beyond the scope of this document,
	but are described in the manual page
	<systemitem>sources.list(5)</systemitem>.
      </para>
    </section>

    <section>
      <title>
	How can I get &aptitude;?
      </title>

      <para>
	In case you are reading this manual but &aptitude; is not yet
	installed on your system, this section explains how to correct
	this unfortunate situation.  Most people should head straight
	for the section on <link linkend='secBinaryPackages'>binary
	packages</link>.
      </para>

      <section id='secBinaryPackages'>
	<title>Pre-built &aptitude; packages, or, <quote>what 99% of users should do</quote></title>

	<para>
	  Pre-built, or <quote>binary</quote> packages are the easiest and most
	  common way to install &aptitude;.  You should only attempt a
	  <link linkend='secSourceInstall'>source install</link> if
	  binary packages are not available for some reason, or if you
	  have unusual needs that are not met by binary packages.
	</para>

	<para>
	  If you are using a Debian system, execute the following
	  command as &root;: <userinput>apt-get install
	  aptitude</userinput>.  If you are not using a Debian system,
	  your system provider might have created a pre-built package
	  of &aptitude;; if you are not sure, you can contact them for
	  further suggestions.
	</para>
      </section>

      <section id='secSourceInstall'>
	<title>Building &aptitude; from source code</title>

	<para>
	  You also can build &aptitude; from source; however, this is
	  probably not a useful exercise unless &apt; is already
	  available on your system.  If it is, you can install
	  &aptitude; from source with the following steps:
	</para>

	<orderedlist>
	  <listitem>
	    <para>
	      Install the following pieces of software:
	    </para>

	    <itemizedlist>
	      <listitem>
		<para>
		  A C++ compiler, such as <ulink
		  url='http://gcc.gnu.org'>g++</ulink>.
		</para>
	      </listitem>

	      <listitem>
		<para>
		  The development files for &apt;, typically available
		  in a package with a name like
		  <systemitem>libapt-pkg-dev</systemitem>.
		</para>
	      </listitem>


	      <listitem>
		<para>
		  The <systemitem>libsigc++-2.0</systemitem> library,
		  available in the package
		  <systemitem>libsigc++-2.0-dev</systemitem> or from
		  <ulink
		  url='http://libsigc.sourceforge.net'></ulink>.
		</para>
	      </listitem>

	      <listitem>
		<para>
		  The <systemitem>cwidget</systemitem> library,
		  available in the package
		  <systemitem>libcwidget-dev</systemitem> or from
		  <ulink
		  url='http://cwidget.alioth.debian.org'></ulink>.
		</para>
	      </listitem>

	      <listitem>
		<para>
		  The <systemitem>gettext</systemitem> program, which
		  should be included with your Linux distribution.
		</para>
	      </listitem>

	      <listitem>
		<para>
		  A <systemitem>make</systemitem> tool, such as <ulink
		  url='http://www.gnu.org/software/make'>GNU
		  make</ulink>.
		</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>
	      Last but not least, download the most recent
	      &aptitude; source code, available from <ulink
	      url='http://packages.debian.org/unstable/admin/aptitude'></ulink>.
	      (scroll to the bottom of the page and download the
	      <quote>.orig.tar.gz</quote> file)
	    </para>
	  </listitem>
	</orderedlist>

	<para>
	  Once all the required components are available, open a
	  terminal and execute the command <command>tar zxf
	  aptitude-&VERSION;.tar.gz</command> to unpack the source
	  code.  Once the source code is unpacked, type <command>cd
	  aptitude-&VERSION; &amp;&amp; ./configure &amp;&amp;
	  make</command> to compile &aptitude;.  If this succeeds,
	  make sure you are the &root; user (by using
	  <command>su</command>, for instance), then type
	  <command>make install</command> to install &aptitude; on
	  your computer.  Once &aptitude; is successfully installed,
	  typing <command>aptitude</command> at a command prompt
	  should start the program.
	</para>
      </section>

      <section>
	<title>Tracking and participating in &aptitude; development</title>

	<section>
	  <title>Getting the &aptitude; development source tree</title>
	  <para>
	    If you want to test the latest bleeding-edge source code
	    for &aptitude;, you can download unreleased &aptitude;
	    source code using Git.  Install Git (available
	    from <ulink url='http://git-scm.com/'/>) and
            execute the command <command>git clone
            git://git.debian.org/git/aptitude/aptitude.git</command>
	    to retrieve the most recent source code.
	  </para>


	  <warning>
	    <para>
	      The &aptitude; Git repository is an active
	      development tree; it will change as bugs are fixed and
	      features are added, and there is absolutely no guarantee
	      that it will even compile, let alone run properly!  Bug
	      reports are welcome, but be aware that you use
	      development code entirely at your own
	      risk!<footnote><para>Of course, all free software is
	      used at your own risk, but the risk involved in using an
	      active development tree is much
	      higher.</para></footnote>
	    </para>
	  </warning>
	</section>

	<section>
	  <title>Mailing list</title>

	  <para>
	    The primary mailing list for &aptitude; development is
	    <email>aptitude-devel@lists.alioth.debian.org</email>.
	    Archives of the list are located at <ulink
	    url='http://lists.alioth.debian.org/pipermail/aptitude-devel/'/>.
	    To subscribe, visit the Web page <ulink
	    url='http://lists.alioth.debian.org/mailman/listinfo/aptitude-devel'/>.
	  </para>
	</section>

	<section>
	  <title>Submitting patches</title>

	  <para>
	    Ideally, patches should be submitted to the &aptitude;
	    mailing list,
	    <email>aptitude-devel@lists.alioth.debian.org</email>.
	    But if you prefer sending them by private email, you may
	    email them to <email>aptitude@packages.debian.org</email>
	    or <email>dburrows@debian.org</email>.  A brief
	    description of the motivation behind your patch, and an
	    explanation of how it works, are greatly appreciated.
	  </para>
	</section>

	<section>
	  <title>Tracking changes to the &aptitude; source tree</title>

	  <para>
	    The &aptitude; source tree is regularly updated with new
	    features, bugfixes, and new bugs.  Once the source code is
	    available on your computer (see the previous section), you
	    can <command>cd</command> into it and type <command>git
	    pull</command> to update it with any changes made to the
	    main repository.
	  </para>

	  <para>
	    To automatically receive notifications when changes are
	    made to the &aptitude; codebase, subscribe to the Atom feed
	    available at <ulink
            url='http://anonscm.debian.org/gitweb/?p=aptitude/aptitude.git;a=atom'/>
            or RSS feed available at <ulink
            url='http://anonscm.debian.org/gitweb/?p=aptitude/aptitude.git;a=rss'/>.
	  </para>
	</section>

	<section>
	  <title>Building &aptitude; from the development tree</title>

	  <para>
	    To build &aptitude; from the Git repository, you must
	    have the programs <systemitem>autoconf</systemitem> and
	    <systemitem>automake</systemitem> installed.  Type
	    <command>sh ./autogen.sh &amp;&amp; ./configure</command>
	    to generate the files needed to compile &aptitude;, then
	    execute <command>make</command> and <command>make
	    install</command>.
	  </para>
	</section>
      </section>
    </section>
  </preface>

  <chapter id='chapGettingStarted'>
    <title>Getting started</title>

    <blockquote>
      <attribution>
	<personname>
	  <firstname>Lao</firstname>
	  <surname>Tsu</surname>
	</personname>
      </attribution>

      <para>
	A journey of a thousand miles must begin with a single step.
      </para>

    </blockquote>

    <para>
      &aptitude; is a sizeable program with many features, and it can
      be a bit overwhelming for new users to get acquainted with it.
      This chapter does not exhaustively describe the features of
      &aptitude; (see <xref linkend='chapRefGuide'/> for that), but it
      does provide a walk-through of the basic and most commonly used
      features of the program.
    </para>

    <section id='secUsingVisual'>
      <title>Using &aptitude;</title>

      <para>
	This section describes how to use the visual interface of
	&aptitude;.  For information on using &aptitude;'s
	command-line interface, see <xref linkend='secUsingCmdline'/>.
      </para>

      <section>
	<title>&aptitude; basics</title>
	<para>
	  To run &aptitude;, open your favorite text terminal, and at
	  the command line, type:
	</para>

	<screen><prompt>foobar$</prompt> <userinput>aptitude</userinput></screen>

	<para>
	  Once the cache is loaded (this may take some time on slower
	  machines), the main &aptitude; screen should appear:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/start-snapshot.png' format='PNG' scalefit='1' width='100%'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--- Installed Packages
--- Not Installed Packages
--- Obsolete and Locally Created Packages
--- Virtual Packages
--- Tasks






These packages are currently installed on your computer.








</screen>
	    </textobject>

	  </mediaobject>
	</screenshot>

	<para>
	  As you can see, the main screen of &aptitude; is divided
	  into several regions.  The blue line at the top of the
	  terminal is the menu bar, and the blue lines below it are
	  informational messages describing some important commands.
	  The black space that follows is the list of all available
	  packages, in which some groups of packages are listed.  The
	  currently selected group (<quote>Installed Packages</quote>) is
	  highlighted, and its description is shown in the lower black
	  space.
	</para>

	<para>
	  As the top line of the screen suggests, you can access
	  &aptitude;'s menus by pressing <keycombo action='simul'><keycap>Control</keycap><keycap>t</keycap></keycombo>; you can
	  also click the mouse on a menu title if your system supports
	  it.  Pressing <keycombo action='simul'><keycap>Control</keycap><keycap>t</keycap></keycombo> will open the Actions menu:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/menu-snapshot.png' format='PNG' scalefit='1' width='100%'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
+-------------------------+  u: Update  g: Download/Install/Remove Pkgs
|Install/remove packages g|
|Update package list     u|
|Forget new packages     f|
|Clean package cache      |eated Packages
|Clean obsolete files     |
|Mark Upgradable         U|
|Play Minesweeper         |
|Become root              |
+-------------------------+
|Quit                    Q|
+-------------------------+
These packages are currently installed on your computer.









Perform all pending installs and removals</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  Use the arrow keys and <keycap>Enter</keycap> to select menu
	  items (or, if your system supports it, click on them with a
	  mouse); to close the menu without selecting anything, press
	  <keycombo><keycap>Control</keycap><keycap>t</keycap></keycombo> again.  The currently highlighted menu
	  item is explained at the bottom of the screen.  If a menu
	  item can be activated using a keyboard shortcut, the
	  shortcut is displayed in the menu: for instance, the command
	  <quote>Update package list</quote> can be activated by pressing
	  <keycap>u</keycap>.
	</para>

	<para>
	  At any time, you can press <keycap>?</keycap> to display an
	  on-line reference to the available keyboard shortcuts.
	</para>
      </section>

      <section>
	<title>Navigating the &aptitude; package list</title>

	<para>
	  The list of packages is the primary interface to &aptitude;.
	  When &aptitude; starts, the list is organized into a number
	  of groups, as can be seen in the following screen shot:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/start-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--- Installed Packages
--- Not Installed Packages
--- Obsolete and Locally Created Packages
--- Virtual Packages
--- Tasks






These packages are currently installed on your computer.








</screen>
	    </textobject>

	  </mediaobject>
	</screenshot>

	<note>
	  <para>
	    Empty groups of packages are automatically hidden by
	    &aptitude;, so you may see more or less groups than appear
	    in this screen shot.
	  </para>
	</note>

	<para>
	  In the screen shot above, the first group (<quote>Installed
	  Packages</quote>) is highlighted to indicate that it is
	  currently selected.  You can move the selection up and down
	  with the arrow keys; note that the description below the
	  package list changes as you do so.  To <quote>expand</quote>
	  a group, press <keycap>Enter</keycap> while the group is
	  selected:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/expand-once-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--\ Installed Packages                                                          
  --- 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
  --- editors - Text editors and word processors
  --- electronics - Programs for working with circuits and electronics
  --- games - Games, toys, and fun programs
  --- gnome - The GNOME Desktop System
  --- graphics - Utilities to create, view, and edit graphics files

These packages are currently installed on your computer.








</screen>
	    </textobject>

	  </mediaobject>
	</screenshot>

	<para>
	  As you can see, the <quote>Installed Packages</quote> group has been
	  expanded to reveal its contents: it contains a number of
	  subgroups, loosely defined by what types of software they
	  contain.  Expanding the <quote>admin</quote> section by selecting it and
	  pressing <keycap>Enter</keycap>, we see:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/expand-twice-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--\ Installed Packages
  --\ admin - Administrative utilities (install software, manage users, etc)    
    --- main - The main Debian archive
  --- base - The Debian base system
  --- devel - Utilities and programs for software development
  --- doc - Documentation and specialized programs for viewing documentation
  --- editors - Text editors and word processors
  --- electronics - Programs for working with circuits and electronics
  --- games - Games, toys, and fun programs
  --- gnome - The GNOME Desktop System

Packages in the 'admin' section allow you to perform administrative tasks such
as installing software, managing users, configuring and monitoring your system,
examining network traffic, and so on.






</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  The <quote>admin</quote> group contains a single subgroup, the <quote>main</quote>
	  Debian archive.  Expanding this group reveals some packages!
	</para>

	<tip>
	  <para>
	    To save time, you can use the <keycap>[</keycap> key to
	    expand all the subgroups of a group at once.  Selecting
	    <quote>Installed Packages</quote> and pressing <keycap>[</keycap> would
	    have immediately revealed the packages in the screenshot
	    below.
	  </para>
	</tip>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/expand-thrice-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1       
--\ Installed Packages
  --\ admin - Administrative utilities (install software, manage users, etc)
    --\ main - The main Debian archive                                          
i     acpid                                                1.0.3-19   1.0.3-19
i     alien                                                8.44       8.44
i     anacron                                              2.3-9      2.3-9
i     apt-show-versions                                    0.07       0.07
i A   apt-utils                                            0.5.25     0.5.25
i     apt-watch                                            0.3.2-2    0.3.2-2
i     aptitude                                             0.2.14.1-2 0.2.14.1-2

The Debian distribution consists of packages from the 'main' section. Every
package in 'main' is Free Software.

For more information about what Debian considers to be Free Software, see
http://www.debian.org/social_contract#guidelines




</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  In addition to the arrow keys, you can move the selection
	  through the package list by a page of information at a time
	  using the <keycap>Page Up</keycap> and <keycap>Page
	  Down</keycap> keys.
	</para>

	<!-- TODO: demonstrate how to look at a package with a long
	     description so this tip is relevant_-->

	<tip>
	  <para>
	    When there is more information in the lower half of the
	    display than fits into the available space, the
	    <keycap>a</keycap> and <keycap>z</keycap> keys can be used
	    to scroll through it.
	  </para>
	</tip>
      </section>

      <section>
	<title>Finding packages by name</title>

	<para>
	  To quickly find a package whose name you know, press
	  <keycap>/</keycap> to open a search dialog:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/search-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1       
i     frozen-bubble                                        1.0.0-5    1.0.0-5
i A   frozen-bubble-data                                   1.0.0-5    1.0.0-5
i     geekcode                                             1.7.3-1    1.7.3-1
i     gfpoken                                              0.25-3     0.25-3
i     ggz-gnome-client                                     0.0.7-2    0.0.7-2
i     ggz-gtk-client                                       0.0.7-1    0.0.7-1
i     ggz-gtk-game-data                                    0.0.7-2    0.0.7-2
i +--------------------------------------------------------------------------+
i |Search for:                                                               |
i |froz                                                                      |
Po|                             [ Ok ]                             [ Cancel ]|
Fr+--------------------------------------------------------------------------+
attempt to shoot bubbles into groups of the same color to cause them to pop. It
features 100 single-player levels, a two-player mode, music and striking
graphics.

This game is widely rumored to be responsible for delaying the Woody release.

URL: http://www.frozen-bubble.org/

</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  As you can see in the above screen shot, a search for
	  <userinput>froz</userinput> finds the
	  <systemitem>frozen-bubble</systemitem> package.  Using
	  &aptitude;'s powerful search language, described in <xref
	  linkend='secSearchPatterns'/>, it is possible to find
	  packages based on many complex criteria.
	</para>

	<tip>
	  <para>
	    You can search backwards in the package list by pressing
	    <keycap>\</keycap>, and you can repeat the last search by
	    pressing <keycap>n</keycap> after closing the search
	    window.
	  </para>
	</tip>

	<para>
	  Sometimes it is useful to hide all packages except those
	  which meet some particular criterion.  To do this, press
	  <keycap>l</keycap>:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/limit-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--- Installed Packages
--- Not Installed Packages
--- Obsolete and Locally Created Packages
--- Virtual Packages
--- Tasks


  +--------------------------------------------------------------------------+
  |Enter the new package tree limit:                                         |
  |apti                                                                      |
  |                             [ Ok ]                             [ Cancel ]|
Th+--------------------------------------------------------------------------+ a








</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  This dialog works exactly like the search dialog, except
	  that instead of highlighting the next package that matches
	  what you typed into the dialog box, it hides all packages
	  which don't match.  For instance, typing
	  <userinput>apti</userinput> into this dialog box and
	  pressing <keycap>Enter</keycap> will hide all packages
	  except those whose names contain <quote>apti</quote>:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/limit-result-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--\ Installed Packages                                                          
  --\ admin - Administrative utilities (install software, manage users, etc)
    --\ main - The main Debian archive
i     aptitude                                             0.2.14.1-2 0.2.14.1-2
i A   synaptic                                             0.51-1     0.51-1
  --\ x11 - The X window system and related software
    --\ main - The main Debian archive
i     xfree86-driver-synaptics                             0.13.3-1   0.13.3-1
--- Not Installed Packages
--- Virtual Packages

These packages are currently installed on your computer.








</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </section>

      <section id='secManagingPackages'>
	<title>Managing packages</title>

	<para>
	  Now that you can move about the list of packages, it's time
	  to start using &aptitude; to install and remove packages.
	  In this section you will learn how to flag packages for
	  installation, deletion, and upgrade.
	</para>

	<tip>
	  <para>
	    You can only change your system's setup as the &root;
	    user.  If you want to experiment with &aptitude;, you can
	    safely run it as any user other than &root; without
	    damaging your system in any way.  &aptitude; will tell you
	    when you try to do something that only &root; can do, and
	    if you want to continue, you must type &root;'s password.
	  </para>
	</tip>

	<para>
	  All changes to a package are performed by first highlighting
	  it in the package list, then pressing a key corresponding to
	  the action which should be performed.  The basic action keys
	  <footnote>
	    <para>
	      You can also change packages using the
	      <guimenu>Package</guimenu> menu; see <xref
	      linkend='secPackageMenu'/> for details.
	    </para>
	  </footnote>
	  are <keycap>+</keycap> to install or upgrade a package,
	  <keycap>-</keycap> to remove a package, and
	  <keycap>=</keycap> to prevent a package from being
	  automatically upgraded (this is known as
	  <firstterm>holding</firstterm> the package).  These actions
	  are not performed immediately; &aptitude; will simply
	  update the package list to show the change that has been
	  requested.
	</para>

	<para>
	  For instance, in the screen shot below, the
	  <systemitem>kaffeine-mozilla</systemitem> package was selected and
	  <keycap>+</keycap> was pushed.  The package is now
	  highlighted in green and the letter <quote>i</quote> has
	  appeared to the left of its name, to indicate that it will
	  be installed; in addition, an estimate of the amount of
	  space that the package will use is displayed.
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/install-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1                  Will use 2925kB of disk space  DL Size: 1375kB
  --\ kde - The KDE Desktop System
    --\ main - The main Debian archive
p     bibletime-i18n                                        &lt;none&gt;     1.4.1-1
p     education-desktop-kde                                 &lt;none&gt;     0.771
p     junior-kde                                            &lt;none&gt;     1.4
piA   kaffeine                                      +2843kB &lt;none&gt;     0.4.3-1
pi    kaffeine-mozilla                              +81.9kB &lt;none&gt;     0.4.3-1
p     karamba                                               &lt;none&gt;     0.17-5
p     kde-devel                                             &lt;none&gt;     4:3.1.2   
p     kde-devel-extras                                      &lt;none&gt;     4:3.1.2
The K Desktop Environment (development files)
A metapackage containing dependencies for the core development suite of KDE
including kdesdk, qt3-designer, and all core KDE -dev packages.







</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<tip>
	  <para>
	    At any time, you can use &undo-undo; to
	    <quote>undo</quote> any change to one or more packages.
	    This is very useful if an action has unforeseen
	    consequences and you want to <quote>take it back</quote>.
	  </para>
	</tip>

	<para>
	  In addition to actions that affect individual packages,
	  another important action is available: typing
	  <keycap>U</keycap> will attempt to upgrade any packages that
	  can be upgraded.  You should use this command on a regular
	  basis to keep your system up-to-date.
	</para>

	<section id='tutorialBroken'>
	  <title>Managing broken packages</title>

	  <para>
	    Sometimes, changing a package's state will cause
	    dependency relationships to become unfulfilled; packages
	    with unfulfilled dependencies are said to be
	    <firstterm>broken</firstterm>.  &aptitude; will warn you
	    when this happens, and explain why it occured.  For
	    instance, here is what happens if I attempt to remove
	    <systemitem>sound-juicer</systemitem>:
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/broken-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	      </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
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.


The following packages depend on sound-juicer and will be broken by its
removal:


  * gnome-desktop-environment depends on sound-juicer

[1(1)/...] Suggest 2 keeps
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>

	  <para>
	    As you can see, &aptitude; displays three indicators that
	    something has gone wrong: first, the number of broken
	    packages is displayed in the upper blue area; second, the
	    lower half of the display changes to describe broken
	    packages that are related to the currently highlighted
	    package; third, a bar appears at the bottom of the screen
	    with a suggestion on how to solve the problem.  To quickly
	    find broken packages in the package list, you can press
	    <keycap>b</keycap> or search for &Sbroken;.
	  </para>

	  <note>
	    <para>
	      The text <literal>[1(1)/...]</literal> indicates the
	      progress of &aptitude;'s dependency resolver.  The first
	      number is the solution that you have currently selected,
	      and the second one is the number of solutions that
	      &aptitude; has already generated.  The presence of the
	      text <quote><literal>...</literal></quote> indicates
	      that there may be additional solutions beyond the ones
	      generated; if &aptitude; knew for certain that it had
	      generated the only possible solution, this indicator
	      would read <literal>[1/1]</literal>.
	    </para>
	  </note>

	  <para>
	    To see more information about how &aptitude; thinks you
	    can solve this problem, press <keycap>e</keycap>.  A
	    screen similar to the following will appear:
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/solution-screen-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	      </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:
    gstreamer0.8-cdparanoia                           [0.8.10-1 (unstable, now)]
    sound-juicer                                                [2.10.1-2 (now)]
















[1(1)/...] Suggest 2 keeps
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>

	  <para>
	    From here, you can see more solutions by pressing
	    <keycap>.</keycap> or return to solutions that you
	    previously examined by pressing <keycap>,</keycap>.  To
	    apply the current solution and return to the package list,
	    press <keycap>!</keycap>.  For instance, pressing
	    <keycap>.</keycap> while the above screen is displayed
	    results in the following solution being presented:
	  </para>

          <informalfigure id='solutionScreenSnapshot2'>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/solution-screen-snapshot2.png' format='PNG' width='100%' scalefit='1'/>
	      </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:
    sound-juicer                                      [2.10.1-3 (unstable, now)]
  --\ Downgrade the following packages:
    gstreamer0.8-cdparanoia          [0.8.11-1 unstable, now -> 0.8.8-3 testing]















[2(2)/...] Suggest 1 keep,1 downgrade
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>
          </informalfigure>

	  <!-- Move to the reference manual? -->
	  <para>
	    In addition to the basic solution navigation commands, you
	    can press <keycap>r</keycap> to <quote>reject</quote>
	    actions of which you disapprove.  For instance, the first
	    solution will cancel the removal of
	    <systemitem>sound-juicer</systemitem> -- the very action
	    we were trying to perform!  By pressing <keycap>r</keycap>
	    on the item corresponding to this action, we can tell
	    &aptitude; that it should not cancel the removal of
	    <systemitem>sound-juicer</systemitem> in this way.
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/solution-screen-snapshot3.png' format='PNG' width='100%' scalefit='1'/>
	      </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:
    gstreamer0.8-cdparanoia                           [0.8.11-1 (unstable, now)]
R   sound-juicer                                      [2.10.1-3 (unstable, now)]






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)]
R -> 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>
	    As you can see, the list item corresponding to keeping
	    <systemitem>sound-juicer</systemitem> at its current
	    version has turned red and been marked with an
	    <quote>R</quote>, indicating that it has been rejected.
	    Solutions that you generate in the future (that is, any
	    solution that you have not yet viewed) will not include
	    this action, although solutions that were already
	    generated and contain this action will be available.
	  </para>

	  <note>
	    <para>
	      In the above screen image, a description of
	      <systemitem>sound-juicer</systemitem> is displayed in
	      the middle of the screen; below it, you can see the
	      dependency that caused <systemitem>sound-juicer</systemitem> to
	      be kept at its current version, along with all the ways to
	      resolve this dependency that &aptitude; knows about.
	    </para>
	  </note>

	  <para>
	    For instance, if this rejection is imposed immediately
	    after attempting to remove <systemitem>sound-juicer</systemitem>,
	    pressing <keycap>.</keycap> retrieves the following
	    solution, skipping the <link
	    linkend='solutionScreenSnapshot2'>solution</link> that
	    cancels the installation of <systemitem>sound-juicer</systemitem>
	    and downgrades <systemitem>gstreamer0.8-cdparanoia</systemitem>.
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/solution-screen-snapshot4.png' format='PNG' width='100%' scalefit='1'/>
	      </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
  --\ Remove the following packages:
    gnome-desktop-environment              [1:2.10.2.3 (unstable, testing, now)]

















[2(2)/...] Suggest 1 removal
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>

	  <para>
	    Rejections are only applied to newly generated solutions:
	    that is, solutions that are generated when you press
	    <keycap>.</keycap> while viewing the last generated
	    solution.  Previously generated solutions can still
	    contain rejections.  You can cancel a rejection at any
	    time by once again selecting the rejected action and
	    pressing <keycap>r</keycap>; this will permit solutions
	    containing the action to be generated again, including any
	    solutions that were previously <quote>skipped</quote>.
	  </para>

	  <para>
	    The opposite of rejecting an action is approving it.  To
	    approve an action, just select it and press
	    <keycap>a</keycap>; this forces the problem resolver to
	    choose the action whenever possible<footnote>
	    <para>
	      Approving an action is slightly different from requiring
	      all solutions to contain the action; what it means is
	      that given a choice between an approved action and a
	      non-approved action, the resolver will always pick the
	      approved action.  If there are several possible approved
	      actions, all of them will be candidates to be placed
	      into the solution.
	    </para>
	    </footnote>.  Approved actions will turn green and will be
	    marked with <quote>A</quote>, as in the following
	    screenshot:
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/solution-screen-snapshot5.png' format='PNG' width='100%' scalefit='1'/>
	      </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
  --\ Remove the following packages:
A   gnome-desktop-environment              [1:2.10.2.3 (unstable, testing, now)]

















[2(2)/...] Suggest 1 removal
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>

	  <important>
	    <para>
	      If you do not resolve any broken dependencies,
	      &aptitude; will automatically implement its current
	      suggestion when you commit your selections by pressing
	      <keycap>g</keycap>.  However, it is hard to
	      automatically solve dependency problems, and you may not
	      be happy with the results, so it is generally better to
	      look at what &aptitude; plans to do
	      <emphasis>before</emphasis> committing your selections.
	    </para>
	  </important>
	</section>
      </section>

      <section>
	<title>Updating the package list and installing packages</title>

	<para>
	  At this point, you know enough about &aptitude; to actually
	  make modifications to your system.
	</para>

	<para>
	  You should periodically update your list of available
	  packages from the Debian servers, to keep track of new
	  packages and new versions of packages.  To do this, press
	  <keycap>u</keycap>.  At any time during the download, you
	  can press <keycap>q</keycap> to abort it.
	</para>

	<para>
	  Once you have fresh lists of packages, you can choose the
	  packages to upgrade, install, or remove as described in the
	  previous section.  To review the actions you have requested,
	  press <keycap>g</keycap> once.  When installing the
	  <systemitem>kaffeine-mozilla</systemitem> package (from the
	  previous example), the following screen appears:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/preview-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1                  Will use 2925kB of disk space  DL Size: 1375kB
--\ Packages being automatically installed to satisfy dependencies               
piA kaffeine                                        +2843kB &lt;none&gt;     0.4.3-1
--\ Packages to be installed
pi  kaffeine-mozilla                                +81.9kB &lt;none&gt;     0.4.3-1







These packages are being installed because they are required by another package
you have chosen for installation.

If you select a package, an explanation of its current state will appear in this
space.




</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  As you can see, &aptitude; automatically decided to install
	  <systemitem>kaffeine</systemitem> for me because
	  <systemitem>kaffeine-mozilla</systemitem> requires it.  At
	  this point, I have the choice of either continuing with the
	  installation by pressing <keycap>g</keycap>, or aborting it
	  by pressing <keycap>q</keycap>.
	</para>
      </section>
    </section>

    <section id='secUsingCmdline'>
      <title>Using &aptitude; from the command line</title>

      <para>
	In addition to its <quote>visual</quote> interface described in the
	previous section, &aptitude; can be used to manage packages
	directly from the command-line in the same way that you would
	use &apt-get;.  This section covers the most common &aptitude;
	command-line actions; for more information, see <link
	linkend='secReference'>the &aptitude; command-line reference</link>.
      </para>

      <para>
	In general, a command-line invocation of &aptitude; will look
	like this:
      </para>

      <cmdsynopsis>
	<command>aptitude</command> <arg
	choice='plain'><replaceable>action</replaceable></arg>
	<arg rep='repeat'><replaceable>arguments</replaceable></arg>
      </cmdsynopsis>

      <para>
	<replaceable>action</replaceable> tells &aptitude; what action
	it is to take; the remaining arguments are used in an
	option-specific fashion.  Typically they will consist of
	package names and command-line switches<footnote><para>A
	<quote>switch</quote> is a letter preceded by a hyphen: for instance, <quote>-a</quote>,
	<quote>-v</quote>, etc.</para></footnote>.
      </para>
      
      <para>
	The most important actions are:
      </para>

      <variablelist>
	<varlistentry>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>update</arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      This command updates the package lists, as if you had
	      entered the visual interface and pressed
	    <keycap>u</keycap>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='safeUpgrade'>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>safe-upgrade</arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      This command will upgrade as many packages as it can
	      upgrade without removing existing packages.
	    </para>

	    <para>
	      It is sometimes necessary to remove one package in order
	      to upgrade another; this command is not able to upgrade
	      packages in such situations.  Use the <link
	      linkend='fullUpgrade'><literal>full-upgrade</literal></link>
	      command to upgrade those packages as well.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='fullUpgrade'>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>full-upgrade</arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      Like <link
	      linkend='safeUpgrade'><literal>safe-upgrade</literal></link>,
	      this command will attempt to upgrade packages, but it is
	      more aggressive about solving dependency problems: it
	      will install and remove packages until all dependencies
	      are satisfied.  Because of the nature of this command,
	      it is possible that it will do undesirable things, and
	      so you should be careful when using it.
	    </para>

	    <note>
	      <para>
		For historical reasons, this command was originally
		named <literal>dist-upgrade</literal>, and that name
		is still recognized by &aptitude;.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <group>
		<arg choice='plain'>install</arg>
		<arg choice='plain'>remove</arg>
		<arg choice='plain'>purge</arg>
	      </group>

	      <arg choice='plain'><replaceable>pkg1</replaceable></arg>
	      <arg rep='repeat'><replaceable>pkg2</replaceable></arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      These commands install, remove, or
	      purge<footnote><para>Purging a package removes the
	      package, as well as all its configuration
	      files.</para></footnote> the specified packages.
	      <quote>Installing</quote> a package which is already installed but
	      can be upgraded will cause it to be upgraded.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>search</arg>
	      <arg choice='plain'><replaceable>pattern1</replaceable></arg>
	      <arg rep='repeat'><replaceable>pattern2</replaceable></arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      This command searches for packages whose name contains
	      any of the given <replaceable>pattern</replaceable>s,
	      printing the result to the terminal.  In addition to
	      just being a string of text, each
	      <replaceable>pattern</replaceable> can be a search
	      pattern as described in <xref
	      linkend='secSearchPatterns'/>.
	      <footnote>
		<para>
		  In fact, the same is true of the commands that take
		  packages as arguments, such as
		  <literal>install</literal> or
		  <literal>show</literal>.
		</para>
	      </footnote> For instance, <quote><literal>aptitude
	      search gnome kde</literal></quote> will list all
	      packages whose name contains either
	      <quote><literal>gnome</literal></quote> or
	      <quote><literal>kde</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>show</arg>
	      <arg choice='plain'><replaceable>pkg1</replaceable></arg>
	      <arg rep='repeat'><replaceable>pkg2</replaceable></arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      Prints information about each
	      <replaceable>pkg</replaceable> to the terminal.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>
	The commands that install, upgrade, and remove packages all
	accept the parameter <literal>-s</literal>, which stands for <quote>simulate</quote>.  When
	<literal>-s</literal> is passed on the command line, the program performs all
	the actions it would normally perform, but does not actually
	download or install/remove any files.
      </para>

      <para>
	&aptitude; will sometimes present a prompt like this:
      </para>

<screen>The following NEW packages will be automatically installed:
  space-orbit-common 
The following NEW packages will be installed:
  space-orbit space-orbit-common 
0 packages upgraded, 2 newly installed, 0 to remove and 0 not upgraded.
Need to get 3200kB of archives. After unpacking 8413kB will be used.
<prompt>Do you want to continue? [Y/n/?]</prompt></screen>

      <para>
	In addition to the obvious options of <quote>Yes</quote> and <quote>No</quote>, a number
	of commands are available which can be used to change the
	information displayed at the prompt, or to specify further
	actions.  For instance, typing <userinput>s</userinput> will display or hide
	information about how much space each package will use:
      </para>

<screen><prompt>Do you want to continue? [Y/n/?]</prompt> <userinput>s</userinput>

Size changes will be shown.

The following NEW packages will be automatically installed:
  space-orbit-common &lt;+8020kB&gt; 
The following NEW packages will be installed:
  space-orbit &lt;+393kB&gt; space-orbit-common &lt;+8020kB&gt; 
0 packages upgraded, 2 newly installed, 0 to remove and 0 not upgraded.
Need to get 3200kB of archives. After unpacking 8413kB will be used.
<prompt>Do you want to continue? [Y/n/?]</prompt></screen>

      <para>
	Similarly, typing <userinput>d</userinput> will display information about
	automatically installed or removed packages:
      </para>

<screen>The following NEW packages will be automatically installed:
  space-orbit-common (D: space-orbit)
The following NEW packages will be installed:
  space-orbit space-orbit-common 
0 packages upgraded, 2 newly installed, 0 to remove and 0 not upgraded.
Need to get 3200kB of archives. After unpacking 8413kB will be used.</screen>

      <para>
	This shows that <systemitem>space-orbit-common</systemitem> is
	being installed because <systemitem>space-orbit</systemitem>
	depends on it.  You can see the entire list of possible
	entries by entering <userinput>?</userinput> at the prompt.
      </para>

      <para>
	If your request violates dependencies in a way that cannot be
	trivially resolved, &aptitude; will ask you what to do:
      </para>

      <screen>The following packages are BROKEN:
  libsdl1.2debian
The following packages will be REMOVED:
  libsdl1.2debian-alsa
.
.
.
The following actions will resolve these dependencies:

Install the following packages:
libsdl1.2debian-all [1.2.12-1 (unstable)]

Score is 41

<prompt>Accept this solution? [Y/n/q/?]</prompt></screen>

      <para>
	Typing <userinput>y</userinput> (or simply pressing
	<keycap>enter</keycap>) will accept the proposed solution.
	Typing <userinput>n</userinput> will display the <quote>next
	best</quote> solution:
      </para>

      <screen><prompt>Accept this solution? [Y/n/q/?]</prompt> <userinput>n</userinput>
The following actions will resolve these dependencies:

Install the following packages:
libsdl1.2debian-esd [1.2.12-1 (unstable)]

Score is 19

<prompt>Accept this solution? [Y/n/q/?]</prompt></screen>

      <para>
	As with the main command-line prompt, you can perform a number
	of additional actions, including manually altering the states
	of packages, from the dependency resolution prompt.  Type
	<userinput>?</userinput> to see a complete list.
      </para>

      <para>
	Typing <userinput>q</userinput> will abort the automatic
	resolver and allow you to resolve the dependencies manually:
      </para>

      <screen><prompt>Accept this solution? [Y/n/q/?]</prompt> <userinput>q</userinput>
aptitude failed to find a solution to these dependencies.  You can solve them yourself by hand or type 'n' to quit.
The following packages have unmet dependencies:
  libsdl1.2debian: Depends: libsdl1.2debian-alsa (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-all (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-esd (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-arts (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-oss (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-nas (= 1.2.12-1) but it is not installable or
                            libsdl1.2debian-pulseaudio (= 1.2.12-1) but it is not installable
Resolve these dependencies by hand? [N/+/-/_/:/?]</screen>

      <para>
	You can use any of the package manipulation commands to
	resolve the broken dependencies (type <userinput>?</userinput>
	for a full list of the available commands).  Type
	<userinput>n</userinput> or press <keycap>enter</keycap> to
	quit &aptitude;:
      </para>

<screen>Resolve these dependencies by hand? [N/+/-/_/:/?] n
Abort.</screen>

      <para>
	For complete documentation of the command-line features of
	&aptitude;, see <xref linkend='secReference'/>.
      </para>
    </section>
  </chapter>

  <chapter id='chapRefGuide'>
    <title>&aptitude; reference guide</title>

    <blockquote>
      <attribution>
	<personname>
	  <firstname>Lewis</firstname>
	  <surname>Carrol</surname>
	  </personname>,
	  <citetitle pubwork='book'>Alice in Wonderland</citetitle>
      </attribution>

      <para>
	The White Rabbit put on his spectacles. 'Where shall I begin,
	please your Majesty?' he asked.
      </para>

      <para>
	'Begin at the beginning,' the King said gravely, 'and go on
	till you come to the end: then stop.'
      </para>
    </blockquote>

    <para>
      &aptitude; is a large program with many features, and it is
      sometimes difficult to remember how to do something, or even to
      remember whether that something is even possible.  Indeed, many
      feature requests received by the author describe features which
      are already present but are difficult to find.<footnote><para>I
      am pleased to say that the number of requests of this sort fell
      off precipitously following the initial publication of this
      Guide.  It would be a happy occurrence if there was a connection
      between the two events.</para></footnote>
    </para>

    <para>
      In an attempt to combat this obscurity, this reference guide
      describes every feature and configuration parameter of
      &aptitude;.  For a more gentle guide to the important features
      of &aptitude;, see <xref linkend='chapGettingStarted'/>.
    </para>

    <note>
      <para>
	&aptitude;'s behavior and appearance can be configured in a
	number of ways.  This manual describes how the program works
	with the default settings; descriptions of how various
	settings affect behavior are given in <xref
	linkend='secConfig'/>.
      </para>
    </note>

    <section>
      <title>The &aptitude; terminal user interface</title>

      <para>
	This section describes the parts of the terminal-based user
	interface of &aptitude; that do not deal with <link
	linkend='secManagingPackages'>managing packages</link>.
      </para>

      <section>
	<title>Using the menus</title>

	<para>
	  The menu bar at the top of the screen lists the most
	  important commands in &aptitude;.  To activate the menu bar,
	  press <keycombo><keycap>Control</keycap><keycap>t</keycap></keycombo>; you can then navigate it using
	  the arrow keys and select a menu item using
	  <keycap>Enter</keycap>.
	</para>

	<para>
	  Some menu items also have <quote>hotkeys</quote>: letters or numbers
	  that can be used to select the item while the menu is
	  active.  These hotkeys are displayed in a brighter shade
	  of white than the rest of the menu.
	</para>

	<para>
	  In addition, some menu items have <quote>shortcuts</quote>:
	  keystrokes that perform the same action as the menu item
	  while the menu is <emphasis>not</emphasis> active.
	  These keystrokes are listed on the right-hand side of
	  the menu.
	</para>

	<para>
	  In the remainder of the manual, menu commands will be
	  written like this:
	  <menuchoice><shortcut><keycap><replaceable>key</replaceable></keycap></shortcut><guimenu><replaceable>Menu</replaceable></guimenu><guimenuitem><replaceable>Item</replaceable></guimenuitem></menuchoice>.
	  This indicates that you should choose
	  <replaceable>Item</replaceable> from the
	  <replaceable>Menu</replaceable> menu, and that
	  <replaceable>key</replaceable> is the shortcut for this
	  command.
	</para>
      </section>

      <section>
	<title>Menu commands</title>

	<section>
	  <title>The Actions menu</title>

	  <figure>
	    <title>Commands available in the Actions menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&actions-install;</entry>
		    <entry>
		      If an installation preview is not visible,
		      display one; otherwise, perform an install run
		      as described in <xref linkend='secInstallRun'/>.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-update;</entry>
		    <entry>
		      Bring the package list up-to-date.
		    </entry>
		  </row>

		  <row id='menuUpgrade'>
		    <entry>&actions-upgrade;</entry>
		    <entry>
		      Flag all upgradable packages, except those which
		      are held or forbidden from upgrading, for
		      upgrade.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-forget;</entry>
		    <entry>
		      Discard all information about what packages are
		      <quote>new</quote> (empty the <quote>New Packages</quote> tree).
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-cancel;</entry>

		    <entry>
		      Cancel all pending installations, removals,
		      upgrades, and holds.  This is equivalent to
		      executing the <link
		      linkend='pkgCmdKeep'>Keep</link> command on
		      every package in the package database.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-clean;</entry>
		    <entry>
		      Delete all the compressed packages that were
		      downloaded by
		      &aptitude;
		      <footnote id='footnoteAptTools'>
			<para>
			  Or any other &apt; utility.
			</para>
		      </footnote>.
		    </entry>
		  </row>

		  <row id='menuCleanObs'>
		    <entry>&actions-clean-obs;</entry>
		    <entry>
		      Delete any compressed packages that were
		      downloaded by &aptitude; <footnoteref
		      linkend='footnoteAptTools'/> and are no longer
		      available.  These are presumed to be packages
		      which are obsolete, and can be deleted to save
		      disk space without requiring an otherwise
		      unnecessary download.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-mine;</entry>
		    <entry>
		      Play a game of Minesweeper, as described in
		      <xref linkend='secMinesweeper'/>.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-su;</entry>
		    <entry>
		      Continue working as the &root; user; see <xref
		      linkend='secBecomingRoot'/>.
		    </entry>
		  </row>

		  <row>
		    <entry>&actions-quit;</entry>
		    <entry>
		      Quit &aptitude;, saving any changes to package
		      states.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>
  
	<section>
	  <title>The Undo menu</title>

	  <figure>
	    <title>Commands available in the Undo menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&undo-undo;</entry>
		    <entry>
		      Cancel the effect of the last change to a
		      package's state, up to the last time &aptitude;
		      was started, the package list was updated, or an
		      install run was performed.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section id='secPackageMenu'>
	  <title>The Package menu</title>

	  <figure>
	    <title>Commands available in the Package menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&package-install;</entry>

		    <entry>
		      Flag the currently selected package for <link
		      linkend='pkgCmdInstall'>installation</link>.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-remove;</entry>

		    <entry>
		      Flag the currently selected package for <link
		      linkend='pkgCmdRemove'>removal</link>.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-purge;</entry>

		    <entry>
		      Flag the currently selected package to be <link
		      linkend='pkgCmdPurge'>purged</link>.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-keep;</entry>

		    <entry>
		      <link linkend='pkgCmdKeep'>Cancel</link> any
		      pending installation, upgrade, or removal of the
		      currently selected package, and remove any hold
		      that was set on the package.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-hold;</entry>
		    <entry>
		      <link linkend='pkgCmdHold'>Hold</link> the
		      currently selected package back.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-markauto;</entry>
		    <entry>
		      Mark the currently selected package as an
		      <quote>automatically installed</quote> package.
		      For more information on manually and
		      automatically installed packages, see <xref
		      linkend='secAutoInstall'/>.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-markmanual;</entry>
		    <entry>
		      Mark the currently selected package as a
		      <quote>manually installed</quote> package.  For
		      more information on manually and automatically
		      installed packages, see <xref
		      linkend='secAutoInstall'/>.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-forbid;</entry>

		    <entry>
		      If a package that can be upgraded is selected,
		      <link linkend='pkgCmdForbid'>forbid</link> it
		      from being upgraded to the currently available
		      version.  If a version of a package is selected,
		      forbid the package from being upgraded to that
		      version.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-information;</entry>

		    <entry>
		      Display a screen containing information about
		      the currently selected package, such as the
		      packages it depends upon, the packages which
		      depend upon it, and its available versions.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-cycle-information;</entry>

		    <entry>
		      When browsing the package list, cycles through
		      the information that can be displayed in the
		      information area (the lower half of the
		      display).  The information area can display the
		      long description of the selected package (its
		      default behavior), a summary of the dependencies
		      related to the package, or an analysis of which
		      other packages require or suggest the selected
		      package.
		    </entry>
		  </row>

		  <row>
		    <entry>&package-changelog;</entry>

		    <entry>
		      Display the currently selected package's Debian
		      changelog.  To see the changelog of a particular
		      version, select that version and execute this
		      command.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</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 id='menuResolverReject'>
		    <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 id='menuResolverApprove'>
		    <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>

		  <row id='menuResolverRejectBreakHolds'>
		    <entry>&resolver-reject-break-holds;</entry>

		    <entry>
		      Reject (as if with &resolver-reject;) all
		      actions that would break a hold on a package or
		      install a forbidden version.  These actions are
		      rejected by default unless <link
		      linkend='configProblemResolver-Allow-Break-Holds'><literal>Aptitude::ProblemResolver::Allow-Break-Holds</literal></link>
		      is set to <literal>true</literal>, but this menu
		      item allows you to reject them manually at any
		      time.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section>
	  <title>The Search menu</title>

	  <figure>
	    <title>Commands available in the Search menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&search-find;</entry>

		    <entry>
		      Find the next package in the package list that
		      matches a search pattern (see <xref
		      linkend='secSearchPatterns'/>).
		    </entry>
		  </row>

		  <row>
		    <entry>&search-find-back;</entry>

		    <entry>
		      Find the previous package in the package list
		      that matches a search pattern (see <xref
		      linkend='secSearchPatterns'/>).
		    </entry>
		  </row>

		  <row>
		   <entry>&search-refind;</entry>

		   <entry>
		     Repeat the last Find command.
		   </entry>
		  </row>

		  <row>
		   <entry>&search-repeat-find-back;</entry>

		   <entry>
		     Repeat the last Find command, but in the opposite
		     direction.  If the last Find command was Find
		     Backwards, this will perform a forwards search,
		     and vice versa.
		   </entry>
		  </row>

		  <row id='menuSearchLimit'>
		    <entry>&search-limit;</entry>

		    <entry>
		      Filter the current package list by removing any
		      packages which do not match a search pattern
		      (see <xref linkend='secSearchPatterns'/>).
		    </entry>
		  </row>

		  <row>
		    <entry>&search-unlimit;</entry>

		    <entry>
		      Un-filter the current package list (all packages
		      will be shown).
		    </entry>
		  </row>

		  <row>
		    <entry>&search-find-broken;</entry>

		    <entry>
		      Find the next broken package.  This is
		      equivalent to searching for &Sbroken;.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section id="secOptionsMenu">
	  <title>The Options menu</title>

	  <figure>
	    <title>Commands available in the Options menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&options-preferences;</entry>

		    <entry>
		      Open a new top-level view in which you can
		      modify &aptitude;'s settings.  Configuration
		      options are displayed in a tree similar to the
		      tree of packages; to enable or disable an
		      option, select it and press
		      <keycap>Space</keycap> or
		      <keycap>Enter</keycap>.  Configuration options
		      are saved to
		      <filename>~/.aptitude/config</filename>
		      immediately upon being selected.
		    </entry>
		  </row>

		  <row>
		    <entry>&options-revert;</entry>

		    <entry>
		      Reset all options to their default values.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section>
	  <title>The Views menu</title>

	  <note>
	    <para>
	      For an overview of how views work, see <xref
	      linkend='secViews'/>.
	    </para>
	  </note>

	  <figure>
	    <title>Commands available in the Views menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&views-next;</entry>

		    <entry>
		      Change to the next active view.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-prev;</entry>

		    <entry>
		      Change to the previous active view.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-close;</entry>

		    <entry>
		      Close the current view.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-new;</entry>

		    <entry>
		      Create a new view of the package list.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-audit;</entry>

		    <entry>
		      Create a view that displays packages which are
		      not installed, and which a package installed on
		      your system Recommends.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-flat;</entry>

		    <entry>
		      Create a new view of the package list in which
		      packages are not categorized.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-debtags;</entry>

		    <entry>
		      Create a new view of the package list in which
		      packages are categorized according to their
		      debtags entries.
		    </entry>
		  </row>

		  <row>
		    <entry>&views-browse;</entry>

		    <entry>
		      View the package list, arranged by category.
		      <!-- TODO: (see <xref linkend='secHier'/>). -->
		    </entry>
		  </row>

		  <row>
		    <entry>Additional items</entry>

		    <entry>
		      A number of additional menu items appear; these
		      correspond to the currently active views.  To
		      switch directly to a view, select it from the
		      menu.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section>
	  <title>The Help menu</title>

	  <figure>
	    <title>Commands available in the Help menu</title>

	    <informaltable>
	      <tgroup cols='2'>
		<thead>
		  <row>
		    <entry>Command</entry>
		    <entry>Description</entry>
		  </row>
		</thead>

		<tbody>
		  <row>
		    <entry>&help-about;</entry>

		    <entry>
		      Display some copyright information.
		    </entry>
		  </row>

		  <row>
		    <entry>&help-help;</entry>

		    <entry>
		      Display the on-line help page.
		    </entry>
		  </row>

		  <row>
		    <entry>&help-manual;</entry>

		    <entry>
		      Display the User's Manual (this document).
		    </entry>
		  </row>

		  <row>
		    <entry>&help-faq;</entry>

		    <entry>
		      Display the <link linkend='chapFAQ'>&aptitude;
		      FAQ</link>.
		    </entry>
		  </row>

		  <row>
		    <entry>&help-changelog;</entry>

		    <entry>
		      Display a history of the major changes made to
		      &aptitude;.
		    </entry>
		  </row>

		  <row>
		    <entry>&help-license;</entry>

		    <entry>
		      Display the terms under which you may copy,
		      modify, and distribute &aptitude;.
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>
      </section>

      <section id='secViews'>
	<title>Working with multiple views</title>

	<para>
	  &aptitude; allows you to work with several <quote>views</quote> at once.
	  A <quote>view</quote> (sometimes called a <quote>screen</quote>) is simply something
	  that can appear in the area of the screen below the menu
	  bar.  The most common view is the package list, but download
	  views are also common.
	</para>

	<para>
	  When several views are open at once, a bar listing all the
	  active views will appear at the top of the screen.  For
	  instance, if I examine <systemitem>apt</systemitem> by
	  pressing <keycap>Enter</keycap>, then examine
	  <systemitem>libc6</systemitem>, the screen will look
	  something like this:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/views-tab-bar.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
         Packages                  apt info                  libc6 info
aptitude 0.3.1       
i A  --\ libc6                                             2.3.2.ds1- 2.3.2.ds1-
  Description: GNU C Library: Shared libraries and Timezone data
    Contains the standard libraries that are used by nearly all programs on the
    system. This package includes shared versions of the standard C library and
    the standard math library, as well as many others. Timezone data is also
    included.
  Priority: required
  Section: base
  Maintainer: GNU Libc Maintainers &lt;debian-glibc@lists.debian.org&gt;
  Compressed size: 4901k
  Uncompressed size: 15.9M
  Source Package: glibc
  --\ Depends
    --- libdb1-compat
  --\ Suggests
    --- locales
    --- glibc-doc
  --\ Conflicts
GNU C Library: Shared libraries and Timezone data</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  You can close the current view using &views-close;.  To
	  switch to the next or previous view, use &views-next; and
	  &views-prev;, or click on the view's name at the top of the
	  screen; you can also find a list of all active views in the
	  Views menu.
	</para>

	<para>
	  As shown above, some commands (for instance, viewing
	  information about a package) will create new views
	  automatically; you can also explicitly create a new view
	  using &views-new; or &views-browse;.
	</para>
      </section>

      <section id='secBecomingRoot'>
	<title>Becoming &root;</title>

	<para>
	  Some actions, such as updating the package lists, can only
	  be performed as &root;.  If you are not &root; and you try
	  to update the package lists, &aptitude; will ask if you want
	  to become &root;:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/become-root-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </imageobject>

	    <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1    
--- Installed Packages
--- Not Installed Packages
--- Obsolete and Locally Created Packages
--- Virtual Packages
--- Tasks

  +-------------------------------------------------------------------------+
  |Updating the package lists requires administrative privileges, which     |
  |you currently do not have.  Would you like to change to the root account?|
  |                                                                         |
  |         [ Become root ]                  [ Don't become root ]          |
Th+-------------------------------------------------------------------------+








</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  If you select <quote>Become root</quote>, &aptitude; will prompt you for
	  &root;'s password; when you have correctly entered it,
	  &aptitude; will perform the action that required &root;
	  privileges.  You will still be &root; after the action
	  completes.
	</para>

	<para>
	  You can switch to the &root; account at any time using the
	  command &actions-su;.  Any changes you have made to package
	  states will be preserved (but will not be saved until you
	  quit &aptitude;).
	</para>

	<para>
	  By default, &aptitude; will use the command
	  <systemitem>su</systemitem> to gain &root; privileges.  If you
	  would like it to use some other command (such as
	  <systemitem>sudo</systemitem>), set the configuration option
	  <link
	  linkend='configGet-Root-Command'><literal>Aptitude::Get-Root-Command</literal></link>.
	</para>
      </section>
    </section>

    <section>
      <title>Managing packages</title>

      <para>
	This section describes how to manipulate the list of packages,
	how to install new packages on your system, and how to remove
	old packages.
      </para>

      <section>
	<title>Managing the package list</title>

	<para>
	  To keep the list of packages up-to-date, it is recommended
	  that you periodically update it.  You can do this using the
	  &actions-update; command.
	</para>
      </section>

      <section id='secAccessingPackageInformation'>
	<title>Accessing package information</title>

	  <para>
	    Information about packages is presented in several
	    locations in &aptitude;: the package list gives a quick
	    overview of the state of each package, and additional
	    views providing detailed information about a package are
	    also available.
	  </para>

	  <section>
	    <title>The package list</title>

	    <para>
	      The package list displays an <quote>at-a-glance</quote> synopsis of a
	      package's state.  For instance, the package
	      <systemitem>webmin</systemitem> might have the
	      following synopsis:
	    </para>

	    <screen>piAU  webmin                                        +5837kB &lt;none&gt;     1.160-2</screen>

	    <para>
	      The four characters on the left-hand side of the
	      synopsis show that the package is not installed
	      (<quote>p</quote>), that it is going to be installed
	      (<quote>i</quote>), that it was automatically chosen to
	      be installed (<quote>A</quote>), and that it is
	      untrusted (<quote>U</quote>).  On the right-hand side of
	      the synopsis, the current version and the most recent
	      available version are displayed, along with an
	      indication of how much space will be used by the
	      upgrade.
	    </para>

	    <tip>
	      <para>
		You can customize how package synopses are displayed;
		see <xref linkend='secDisplayFormat'/> for details.
	      </para>
	    </tip>

	    <para>
	      The four status flags on the left-hand side of the
	      screen give the basic information about a package's
	      state.  The first character is the package's
	      <emphasis>current state</emphasis>.  The second
	      character is the <emphasis>action</emphasis> which will
	      be taken on the package.  The third character indicates
	      whether the package was <emphasis>automatically
	      installed</emphasis> (see <xref
	      linkend='secAutoInstall'/>), and the fourth character
	      indicates whether the package is trusted (see <xref
	      linkend='secTrust'/>).
	    </para>

	    <para>
	      The possible values of the <quote>current state</quote> flag are
	      given in <xref linkend='figureCurrentFlag'/> and the
	      possible values of the <quote>action</quote> flag are given in <xref
	      linkend='figureActionFlag'/>.
	    </para>

	    <figure id='figureCurrentFlag'>
	      <title>Values of the <quote>current state</quote> flag</title>

	      <informaltable colsep='0' frame='none'>

		<tgroup cols='3'>
		  <tbody>
		    <row>
		      <entry><computeroutput>i</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package is installed and all its
			dependencies are satisfied.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>c</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package was removed, but its configuration
			files are still present.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>p</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package and all its configuration files
			were removed, or the package was never
			installed.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>v</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package is virtual.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>B</computeroutput></entry>
		      <entry>-</entry>
		      <entry>the package has broken dependencies.</entry>
		    </row>

		    <row>
		      <entry><computeroutput>u</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package has been unpacked but not
			configured.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>C</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			half-configured: the package's configuration
			was interrupted.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>H</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			half-installed: the package's installation was
			interrupted.
		      </entry>
		    </row>
		  </tbody>
		</tgroup>
	      </informaltable>
	    </figure>

	    <figure id='figureActionFlag'>
	      <title>Values of the <quote>action</quote> flag</title>

	      <informaltable colsep='0' frame='none'>
		<tgroup cols='3'>
		  <tbody>
		    <row>
		      <entry><computeroutput>i</computeroutput></entry>
		      <entry>-</entry>
		      <entry>the package will be installed.</entry>
		    </row>

		    <row>
		      <entry><computeroutput>u</computeroutput></entry>
		      <entry>-</entry>
		      <entry>the package will be upgraded.</entry>
		    </row>

		    <row>
		      <entry><computeroutput>d</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package will be deleted: it will be
			removed, but its configuration files will
			remain on the system.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>p</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package will be purged: it and its
			configuration files will be removed.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>h</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package will be held back: it will be kept
			at its current version, even if a newer
			version becomes available, until the hold is
			cancelled.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>F</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			An upgrade of the package has been forbidden.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>r</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package will be reinstalled.
		      </entry>
		    </row>

		    <row>
		      <entry><computeroutput>B</computeroutput></entry>
		      <entry>-</entry>
		      <entry>
			the package is <quote>broken</quote>: some of its
			dependencies will not be satisfied.
			&aptitude; will not allow you to install,
			remove, or upgrade anything while you have
			broken packages.
		      </entry>
		    </row>
		  </tbody>
		</tgroup>
	      </informaltable>
	    </figure>

	    <para>
	      In addition, &aptitude; will use colors to indicate
	      package state if your terminal supports it.  State
	      distinctions are mainly displayed using the background
	      color:
	    </para>

	    <variablelist>
	      <varlistentry>
		<term>Black</term>
		<listitem>
		  <para>
		    The package cannot be upgraded (or is not going to
		    be installed), and it has no dependency problems.
		    If the package is installed, its name will be
		    highlighted.
		  </para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>Green</term>
		<listitem>
		  <para>
		    The package is going to be installed.
		  </para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>Blue</term>
		<listitem>
		  <para>
		    The package is currently installed, and it will be
		    upgraded.
		  </para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>Magenta</term>
		<listitem>
		  <para>
		    The package is currently installed, but it will be
		    removed.
		  </para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>White</term>
		<listitem>
		  <para>
		    The package is currently installed, and it is
		    <quote>held</quote> at its current version: automatic upgrades
		    will ignore it.
		  </para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>Red</term>
		<listitem>
		  <para>
		    This package is broken: some of its dependencies
		    will not be satisfied.
		  </para>
		</listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    Finally, the lower half of the screen displays the long
	    description.  &aptitude; will attempt to detect whether
	    the package is involved in a dependency problem; if so,
	    information regarding the dependency problem will be
	    displayed here.  To cycle between dependency information
	    and the package description, press <keycap>i</keycap>.
	  </para>
	</section>

	<section id='secPackageInfo'>
	  <title>Detailed package information</title>

	  <para>
	    Pressing <keycap>Enter</keycap> while a package is
	    highlighted will display the package information screen:
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/info-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	      </imageobject>

	      <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
i A --\ apt                                                0.5.25     0.5.25
  Description: Advanced front-end for dpkg
    This is Debian's next generation front-end for the dpkg package manager. It
    provides the apt-get utility and APT dselect method that provides a simpler,
    safer way to install and upgrade packages.

    APT features complete installation ordering, multiple source capability and
    several other unique features, see the Users Guide in apt-doc.
  Essential: yes
  Priority: important
  Section: base
  Maintainer: APT Development Team &lt;deity@lists.debian.org&gt;
  Compressed size: 970k
  Uncompressed size: 2961k
  Source Package: apt
  --\ Depends
    --- libc6 (>= 2.3.2.ds1-4)
    --- libgcc1 (>= 1:3.3.3-1)
    --- libstdc++5 (>= 1:3.3.3-1)
  --\ Suggests
    --- aptitude | synaptic | gnome-apt | wajig
    --- dpkg-dev
    --\ apt-doc (UNSATISFIED)                                                   
p     0.6.25
p     0.5.25
  --\ Replaces
    --- libapt-pkg-doc (&lt; 0.3.7)
    --- libapt-pkg-dev (&lt; 0.3.7)
  --- Package names provided by apt
  --- Packages which depend on apt
  --\ Versions
p A 0.6.25
i A 0.5.25

</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>

	  <para>
	    This display can be navigated in a manner similar to the
	    package list: for instance, in the screenshot above, I
	    expanded the dependency on
	    <systemitem>apt-doc</systemitem>, revealing the available
	    versions of <systemitem>apt-doc</systemitem> which will
	    fulfill the dependency.  These versions can be manipulated
	    in the same way that packages can: for instance, to
	    install version <systemitem>0.5.25</systemitem> of
	    <systemitem>apt-doc</systemitem>, you would highlight it
	    and press <keycap>+</keycap>.
	  </para>

	  <tip>
	    <para>
	      To quickly satisfy a dependency, select the dependency
	      and press <keycap>+</keycap>; &aptitude; will
	      attempt to automatically satisfy it.
	    </para>
	  </tip>

	  <para>
	    In addition to the dependencies of a package, you can view
	    the package names that it Provides, the packages which
	    depend upon it, and the available versions of the package
	    (including any other packages that Provide it).
	  </para>

	  <para>
	    As usual, you can dismiss this screen and return to the
	    main view by pressing <keycap>q</keycap>.  For
	    convenience, a few other information screens (which only
	    display some commonly-used information, hiding the rest)
	    are available: press <keycap>v</keycap> to view the
	    versions of a package, <keycap>d</keycap> to view the
	    dependencies of a package, and <keycap>r</keycap> to view
	    the <quote>reverse dependencies</quote> of a package (packages which
	    depend upon it).
	  </para>
	</section>
      </section>

      <section>
	<title>Modifying package states</title>

	<para>
	  The following commands are available to modify the states of
	  packages.  Commands take effect the next time you perform an
	  <link linkend='secInstallRun'>install run</link>; until you
	  do, all of these commands can be reversed using &undo-undo;.
	</para>

	<para>
	  To apply a command to a package, simply select the package
	  in a package list and issue the command.  These commands can
	  also be applied to groups of packages by selecting the group
	  header (for instance, <quote>Upgradable Packages</quote>) and issuing the
	  command.
	</para>

	<informaltable colsep='0' frame='all'>
	  <tgroup cols='2'>
	    <thead>
	      <row>
		<entry>Command</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row id='pkgCmdInstall'>
		<entry>Install: &package-install;</entry>

		<entry>
		  <para>Flag the current package for installation.</para>

		  <para>
		    If the package is not installed, it will be
		    installed.  If it is already installed, it will be
		    upgraded if possible and any sticky upgrade
		    prevention that is in effect (eg, Hold) will be
		    cancelled.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdRemove'>
		<entry>Remove: &package-remove;</entry>

		<entry>
		  <para>Flag the currently selected package for
		  removal.</para>

		  <para>
		    If the package is installed, it will be removed.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdPurge'>
		<entry>Purge: &package-purge;</entry>

		<entry>
		  <para>Flag the current package to be purged.</para>

		  <para>
		    If the package is installed, it will be removed.
		    Furthermore, even if it is removed, any remaining
		    files (such as configuration files) related to the
		    package will be removed from the system.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdKeep'>
		<entry>Keep: &package-keep;</entry>

		<entry>
		  <para>
		    Flag the current package to be kept at its current
		    version.
		  </para>

		  <para>
		    Any action that was to be performed on the package
		    -- installation, removal, or upgrade -- is
		    cancelled, and any persistent hold that was set on
		    the package is removed.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdHold'>
		<entry>Hold: &package-hold;</entry>

		<entry>
		  <para>
		    Set a persistent hold on the package.
		  </para>

		  <para>
		    As with Keep, any action that was to be performed
		    on the package is cancelled.  In addition, the
		    package will not be automatically upgraded
		    <footnote id='footAutoUpgrade'>
		      <para>
			That is, it will be unaffected by
			&actions-upgrade; or the <link
			linkend='fullUpgrade'><literal>full-upgrade</literal></link>
			or <link
			linkend='safeUpgrade'><literal>safe-upgrade</literal></link>
			command-line actions.
		      </para>
		    </footnote>
		    until the hold is removed.  You may cancel a hold
		    by issuing the Install command.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdForbid'>
		<entry>&package-forbid;</entry>

		<entry>
		  <para>
		    The package will not be automatically
		    upgraded<footnoteref linkend='footAutoUpgrade'/>
		    to the version it would currently be upgraded to.
		    If it was going to be upgraded, the upgrade will
		    be cancelled.
		  </para>

		  <para>
		    If you issue this command on a particular version
		    of a package, the package will not be upgraded to
		    the selected version.  Note that only one version
		    can be forbidden at once.
		  </para>

		  <para>
		    This functionality is largely provided as a
		    convenience for users of the <quote>unstable</quote>
		    distribution, so they can avoid known-bad versions
		    of packages.
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdReinstall'>
		<entry>
		  <para>
		    Reinstall: press <keycap>L</keycap>
		  </para>
		</entry>

		<entry>
		  <para>
		    Reinstalls the package.
		  </para>

		  <para>
		    Note that the reinstallation will not be saved
		    when you quit &aptitude; or perform an install run,
		    for technical reasons (essentially, the
		    underlying software layers
		    (<command>dpkg</command> and &apt;) do not provide
		    any way to find out whether a reinstallation was
		    successful or not).
		  </para>
		</entry>
	      </row>

	      <row id='pkgCmdAuto'>
		<entry>&package-markauto;, &package-markmanual;</entry>

		<entry>
		  Sets whether the package is treated as having been
		  automatically installed; automatically installed
		  packages will be removed when no other package
		  requires them.  For more information, see <xref
		  linkend='secAutoInstall'/>.
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>


	<para>
	  In addition to these commands that affect the selected
	  package, there are two commands that affect large numbers of
	  packages at once regardless of what is selected.
	  &actions-forget; clears the <quote>new</quote> status of all packages in
	  the package list, and &actions-upgrade; flags every package
	  which can be upgraded for upgrade, except for packages that
	  are held back or would be upgraded to a forbidden version.
	</para>

	<note>
	  <para>
	    All changes to package states are saved when you quit
	    &aptitude;, update the package list, or perform an install
	    run.  If you do not wish to save your changes, you can
	    always abort &aptitude; by pressing
	    <keycap>Ctrl-C</keycap>.
	  </para>
	</note>
      </section>

      <section id='secInstallRun'>
	<title>Downloading, installing, and removing packages</title>

	<para>
	  Changing package states as described in the previous section
	  does not actually affect what is installed on your system.
	  Thus, you can adjust the state of packages without affecting
	  your system until you are happy with what you see; once you
	  are, you can <quote>commit</quote> the changes by actually installing and
	  removing packages.<footnote><para>This is sometimes referred
	  to as an <quote>install run</quote>, even though you might be upgrading
	  or removing packages in addition to installing
	  them.</para></footnote>
	</para>

	<para>
	  To commit your changes, use the &actions-install; command.
	  Selecting this command will display a preview screen
	  describing the changes that will be performed.  This screen
	  is just a package list, and you can manipulate the packages
	  (for instance, cancelling unwanted removals) in the same way
	  that you could in the main list.
	</para>

	<para>
	  When you are done, use &views-close; to cancel the
	  installation, or use &actions-install; to proceed.
	  &aptitude; will download any files that need to be
	  downloaded, then prompt you to continue with the
	  installation.  When you select <quote>Continue</quote>, the installations
	  and removals will commence.
	</para>

	<para>
	  Packages that are downloaded by &aptitude; are placed in a
	  cache directory (typically
	  <filename>/var/cache/apt/archives</filename>).  Normally,
	  they are just left in this directory ad infinitum.  To
	  delete all the files in this directory, use &actions-clean;;
	  to delete only files which cannot be downloaded again (ie,
	  obsolete packages), use &actions-clean-obs;.
	</para>
      </section>

      <section id='secTrust'>
	<title>Understanding and managing package trust</title>

	<para>
	  &apt;'s ability to access multiple package sources leads to
	  a potential security vulnerability.  Suppose you add an
	  archive of packages published by Joe Random Hacker to your
	  <filename>sources.list</filename> file in order to install
	  Joe's <systemitem>gargleblast</systemitem> package.  It is
	  possible, however, that -- unbeknownst to you -- Joe's
	  archive also contains his own <quote>customized</quote>
	  versions of packages such as <systemitem>libc6</systemitem>
	  and <systemitem>ssh</systemitem>...versions that steal your
	  private information or open backdoors on your system!  If
	  these packages have higher version numbers than the
	  legitimate Debian packages, &apt; will blithely install them
	  on your system during your next upgrade, allowing Joe to do
	  his dirty work undetected.  Joe could also break into your
	  mirror of the Debian archives and replace the legitimate
	  software with his doctored version.
	</para>

	<para>
	  Luckily, newer versions of &apt; and &aptitude;, such as the
	  version documented in this manual, have built-in safeguards
	  to help defeat this type of attack.  &apt; uses strong
	  security mechanisms based on the popular <ulink
	  url='http://www.gnupg.org'>GPG</ulink> encryption software
	  to verify that the packages being distributed from the
	  official Debian mirrors are the same packages that were
	  uploaded by the Debian developers.  &aptitude; will then
	  warn you if you attempt to install a package from a
	  non-Debian source, or if you attempt to upgrade a package
	  that was installed from a Debian source to a version that
	  came from a non-Debian source.
	</para>

	<warning>
	  <para>
	    The security mechanisms in &apt; provide a near-perfect
	    guarantee that the contents of your archive mirror are
	    identical to the contents of the master Debian archive.
	    However, they are not a panacea: for instance, there are
	    many ways that a tampered package could theoretically find
	    its way into the master Debian archive.
	  </para>

	  <para>
	    Ensuring that you only install software from a trusted
	    source will give you an important degree of protection
	    against malicious packages, but it cannot eliminate all
	    the risks inherent in installing software.
	  </para>
	</warning>

	<section>
	  <title>Understanding trust</title>

	  <para>
	    &apt; allows the administrator of an archive to provide a
	    <firstterm>signature</firstterm> of the archive's index.
	    This signature, which (for all practical purposes) cannot
	    be forged, indicates that the package files listed in the
	    index are the same files that the administrator intended
	    to place in the archive: ie, that the contents of the
	    archive have not been tampered with since it was
	    created.<footnote><para>As noted above, it does
	    <emphasis>not</emphasis> indicate that the packages in the
	    archive are secure, or even non-malicious; it merely shows
	    that they are genuine.</para></footnote> The signature can
	    be validated by checking that it corresponds to the
	    administrator's <firstterm>public key</firstterm>.  The
	    public key of the Debian archive is distributed with
	    &apt;, typically on your Debian CD.
	  </para>

	  <para>
	    When &aptitude; downloads an archive index, it will check
	    whether the index is properly signed.  If it is unsigned,
	    &aptitude; will not trust package files from that
	    archive. (see below for information on what this means) If
	    it has a signature but the signature is incorrect or
	    cannot be verified, a warning will be printed and
	    &aptitude; will refuse to trust packages from that
	    archive.
	  </para>

	  <para>
	    Later, when you perform an <link
	    linkend='secInstallRun'>install run</link>, &aptitude;
	    will check whether the packages are from trusted sources.
	    If an untrusted package is being installed, or a package
	    is being upgraded from a trusted to an untrusted version,
	    a warning will be displayed and you will have the
	    opportunity to abort the download:
	  </para>

	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref='images/trust-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	      </imageobject>

	      <textobject role='text'>
<screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.3.0                    Will use 831kB of disk space   DL Size: 30.4MB
--\ Packages to be upgraded
iu U wesnoth                                       -98.3kB 0.8.7-1    0.8.8-1.0w
iuAU wesnoth-data                                  +930kB  0.8.7-1    0.8.8-1.0w
+------------------------------------------------------------------------------+
|WARNING: untrusted versions of the following packages will be installed!     #|
|                                                                             #|
|Untrusted packages could compromise your system's security.  You should only #|
|proceed with the installation if you are certain that this is what you want  #|
|to do.                                                                       #|
|                                                                             #|
|  * wesnoth [version 0.8.8-1.0wesnoth.org]                                   #|
|  * wesnoth-data [version 0.8.8-1.0wesnoth.org]                              #|
|  * wesnoth-music [version 0.8.8-1.0wesnoth.org]                             #|
|         [ Really Continue ]                  [ Abort Installation ]          |
+------------------------------------------------------------------------------+
                                                                               #
                                                                               #
                                                                               #
                                                                               #
                                                                               #
                                                                               #</screen>
	      </textobject>
	    </mediaobject>
	  </screenshot>
	</section>

	<section>
	  <title>Trusting additional keys</title>

	  <para>
	    You might find it useful to allow &apt; to trust
	    additional archives, besides the main Debian archive.  For
	    each archive that you want to trust, you will have to
	    acquire the public key that is used to sign the archive's
	    package index.  This is typically a text file whose name
	    ends in <filename>.asc</filename>; it might be provided by
	    the site administrator or downloadable from a public
	    keyserver.  For more information on what public keys are
	    and how to get them, see the <ulink
	    url='http://www.gnupg.org'>GPG web page</ulink>.
	  </para>

	  <para>
	    The list of keys that apt will trust is stored in the
	    <firstterm>keyring file</firstterm>
	    <filename>/etc/apt/trusted.gpg</filename>.  Once you have
	    the GPG key, you can add it to this file by executing the
	    command <command>gpg --no-default-keyring --keyring
	    /etc/apt/trusted.gpg --import
	    <replaceable>newkey.asc</replaceable></command>.
	    &aptitude; will then trust any archive that is signed with
	    the key contained in <filename>newkey.asc</filename>.
	  </para>

	  <warning>
	    <para>
	      Once an archive's key has been added to the APT keyring,
	      it will be trusted just as much as the main Debian
	      mirrors themselves!  You should only do this if you are
	      very confident that the key you are adding is correct
	      <emphasis>and</emphasis> that the person who holds the
	      key is trustworthy and competent.
	    </para>
	  </warning>
	</section>
      </section>

      <section id='secAutoInstall'>
	<title>Managing automatically installed packages</title>

	<para>
	  To install one package, it is often necessary to install
	  several others (to fulfill its dependencies).  For instance,
	  if you wish to install the
	  <systemitem>clanbomber</systemitem> package, you must also
	  install the package <systemitem>libclanlib2</systemitem>.
	  If you remove <systemitem>clanbomber</systemitem> again, you
	  probably no longer need the
	  <systemitem>libclanlib2</systemitem> package; &aptitude;
	  will attempt to detect this and automatically remove the
	  <systemitem>libclanlib2</systemitem> package.
	</para>

	<para>
	  It works like this: when you install a package, &aptitude;
	  will automatically install any other packages on which it
	  depends.  These packages are marked as having been
	  <quote>automatically installed</quote>; &aptitude; will monitor them and
	  remove them when they are no longer depended upon by any
	  manually installed package
	  <footnote>
	    <para>
	      More precisely: they will be removed when there is no
	      path via Depends, PreDepends, or Recommends to them from
	      a manually installed package.  If <link
	      linkend='configKeep-Suggests'>Aptitude::Keep-Suggests</link>
	      is true, a Suggests relationship is also enough to keep
	      a package installed.
	    </para>
	  </footnote>
	  .  They will appear in the preview as
	  <quote>packages being removed because they are no longer used.</quote>
	</para>

	<para>
	  As with any automatic process, there is a potential for
	  things to go haywire.  For instance, even if a package was
	  automatically installed to start with, it might turn out to
	  be useful in its own right.  You can cancel the <quote>automatic</quote>
	  flag at any time by pressing <keycap>m</keycap>; if the
	  package is already being removed, you can use
	  &package-install; to cancel the removal and clear the
	  <quote>automatic</quote> flag.
	</para>
      </section>
    </section>

    <section id='secDependencyResolution'>
      <title>Resolving package dependencies</title>

      <section>
	<title>Dependency resolution in &aptitude;</title>

	<para>
	  There are two main dependency resolution algorithms in
	  &aptitude;.
	</para>

	<para>
	  The first is an algorithm that is also used by programs such
	  as &apt-get; and <command>synaptic</command>; I will call
	  it <quote>immediate resolution</quote>.  It is invoked
	  whenever you select a package for installation
	  interactively, and immediately after one or more packages
	  are marked for installation at the command-line.  Immediate
	  resolution is fast and will solve most dependency problems,
	  but it is sometimes unable to find any solution.
	</para>

	<para>
	  The second algorithm, which I will call <quote>interactive
	  resolution</quote>, is invoked when packages have broken
	  dependencies even after immediate
	  resolution<footnote><para>Or when immediate resolution is
	  disabled.</para></footnote>.  It can resolve more
	  dependencies, it allows you to review a solution before
	  applying it, and it allows you to provide feedback to the
	  resolver, guiding it towards a better solution.
	</para>
      </section>

      <section id='secImmediateResolution'>
	<title>Immediate dependency resolution</title>

	<para>
	  Whenever you choose to install or upgrade a package in
	  &aptitude;, &aptitude; makes an immediate attempt to resolve
	  any of its dependencies that are not fulfilled.  For each
	  unsatisfied dependency (either a <quote>Depends</quote>, a
	  <quote>Recommends</quote>, or a <quote>Conflicts</quote>),
	  it performs the following steps:
	</para>

	<orderedlist>
	  <listitem>
	    <para>
	      If the dependency is a recommendation, &aptitude; tries
	      to guess whether it is a <quote>new</quote>
	      recommendation or a <quote>previously satisfied</quote>
	      recommendation.  &aptitude; considers a recommendation
	      to be <quote>new</quote> if the package declaring the
	      recommendation is not currently installed, or if its
	      installed version does not recommend a package of the
	      same name.  On the other hand, a recommendation is
	      <quote>previously satisfied</quote> if the package
	      declaring the recommendation is installed, the currently
	      installed version recommends a package of the same name,
	      and that recommendation is currently fulfilled.
	    </para>

	    <para>
	      For example: suppose that version <literal>1.0</literal>
	      of <literal>prog</literal> recommends version
	      <literal>4.0</literal> of <literal>libcool1</literal>,
	      but version <literal>2.0</literal> of
	      <literal>prog</literal> recommends version
	      <literal>5.0</literal> of <literal>libcool1</literal>,
	      and also recommends <literal>apache</literal>.  If you
	      choose to upgrade <literal>prog</literal> from version
	      <literal>1.0</literal> to version
	      <literal>2.0</literal>, the recommendation of
	      <literal>apache</literal> will be considered to be
	      <quote>new</quote> because version
	      <literal>1.0</literal> of <literal>prog</literal> did
	      not recommend <literal>apache</literal>.  On the other
	      hand, the recommendation of <literal>libcool1</literal>
	      is <emphasis>not</emphasis> <quote>new</quote>, because
	      version <literal>1.0</literal> of
	      <literal>prog</literal> recommended
	      <literal>libcool1</literal>, even though it recommended
	      a different version.  However, if
	      <literal>libcool1</literal> is installed, then that
	      recommendation will be considered to be
	      <quote>previously satisfied</quote>.
	    </para>

	    <para>
	      If the configuration option <link
	      linkend='configAptInstall-Recommends'><literal>Apt::Install-Recommends</literal></link>
	      is <literal>true</literal>, &aptitude; will always
	      attempt to fulfill <quote>new</quote> and
	      <quote>previously satisfied</quote> recommendations; all
	      others will be ignored by immediate resolution.  If that
	      option is <literal>false</literal>, immediate dependency
	      resolution will ignore <emphasis>all</emphasis>
	      recommendations.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      If the dependency is on several packages combined with
	      OR, examine each of the alternatives in the order that
	      they are given.  For instance, if a package depends on
	      <quote><literal>exim |
	      mail-transport-agent</literal></quote>, &aptitude; will
	      first process <literal>exim</literal>, then
	      <literal>mail-transport-agent</literal>.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      For each alternative, attempt to resolve it.  If the
	      dependency is a conflict, remove the current alternative
	      if it is installed (and for an unversioned conflict,
	      also remove any package providing the target of the
	      conflict).  Otherwise, install the candidate version of
	      the current alternative if it satisfies the dependency.
	      If not, or if there is no candidate version (for
	      instance, because the current alternative is a virtual
	      package), and if the dependency is unversioned, attempt
	      to install the highest-priority
	      package<footnote><para>The package with the highest
	      <command>dpkg</command> priority, not the package with
	      the highest &apt; pin priority.</para></footnote> whose
	      candidate version provides the target of the current
	      alternative.
	    </para>

	    <para>
	      For instance, say we are attempting to resolve
	      <quote><literal>Depends: exim |
	      mail-transport-agent</literal></quote>.  &aptitude; will
	      first attempt to install the package
	      <literal>exim</literal>.  If <literal>exim</literal> is
	      not available, &aptitude; will then attempt to install
	      the highest-priority package whose candidate version
	      provides <literal>exim</literal>.  If there is no such
	      package, &aptitude; will install the highest-priority
	      package whose candidate version provides the virtual
	      package <literal>mail-transport-agent</literal>.  On the
	      other hand, suppose that the dependency is
	      <quote><literal>Depends: exim (>= 2.0.0) |
	      mail-transport-agent</literal></quote>, but only version
	      <literal>1.0</literal> of <literal>exim</literal> is
	      available.  In this case, &aptitude; will not install
	      <literal>exim</literal> (because the version does not
	      match), nor will it attempt to install packages
	      providing <literal>exim</literal> (because virtual
	      packages cannot match a dependency with a version
	      restriction).  Thus, &aptitude; will fall back to
	      installing the highest-priority package whose candidate
	      version provides
	      <literal>mail-transport-agent</literal>.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      If a package was installed by the previous step, resolve
	      its dependencies using this algorithm, then stop.
	    </para>
	  </listitem>
	</orderedlist>

	<para>
	  While this technique very often solves all the outstanding
	  package dependencies, it can fail in a number of common
	  circumstances.
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      Conflicts are resolved by removing the package that is
	      the target of the conflict.  But now other packages that
	      depend on this package have unresolved dependencies; the
	      immediate resolver makes no attempt to fix them.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      A dependency might not be satisfiable due to version
	      restrictions and due to the limitation that only
	      candidate versions are considered.  For instance, say
	      that versions <literal>1.0</literal> and
	      <literal>2.0</literal> of <literal>fileutils</literal>
	      are available, that the candidate version is
	      <literal>1.0</literal>, and that the package
	      <literal>octopus</literal> declares a dependency
	      <quote><literal>Depends: fileutils (>=
	      2.0)</literal></quote>.  Immediate resolution is unable
	      to resolve this dependency: it will never consider
	      version <literal>2.0</literal> of the package, since
	      that is not the candidate version.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>
	  The interactive dependency resolver can solve these
	  situations and more.  When there are broken dependencies
	  left over, or when immediate dependency resolution is
	  disabled, the interactive resolver will automatically start
	  searching for a solution.  The next section describes how to
	  use the interactive dependency resolver.
	</para>
      </section>

      <section id='secResolver'>
	<title>Resolving Dependencies Interactively</title>

	<para>
	  If a dependency problem arises that cannot be handled using
	  the immediate dependency resolver, &aptitude; can assist you
	  in resolving it.  As soon as a problem occurs, a red bar
	  will appear at the bottom of the screen with a summary of
	  &aptitude;'s suggestion about how to fix it.  For instance,
	  in the following screenshot, &aptitude; is indicating that
	  it can resolve the situation by keeping two packages at
	  their current versions.
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/broken-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </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
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.


The following packages depend on sound-juicer and will be broken by its
removal:


  * gnome-desktop-environment depends on sound-juicer

[1(1)/...] Suggest 2 keeps
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  As indicated at the bottom of the screen, you can view
	  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>.  When you examine the
	  current solution, a screen similar to the following will
	  appear:
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/solution-screen-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </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:
    gstreamer0.8-cdparanoia                           [0.8.10-1 (unstable, now)]
    sound-juicer                                                [2.10.1-2 (now)]
















[1(1)/...] Suggest 2 keeps
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  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-explanation-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </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:
    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,
	  any one of them could be chosen).  On the other hand, if you
	  <firstterm>reject</firstterm> an action, the resolver will
	  never choose that action.
	</para>

	<para>
	  To reject an action, 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; press
	  <keycap>a</keycap> again to restore its original state.  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>

	<note>
	  <para>
	    By default, the resolver rejects actions that change the
	    state of held packages, or that install forbidden versions
	    of packages.  You can override these rejections, thus
	    allowing the hold or forbidding to be automatically
	    overridden, in the same way that you would override any
	    other rejection.  Setting the configuration option <link
	    linkend='configProblemResolver-Allow-Break-Holds'><literal>Aptitude::ProblemResolver::Allow-Break-Holds</literal></link>
	    to <literal>true</literal> will disable this behavior,
	    meaning that the resolver will always break holds (albeit
	    at a penalty, see <link
	    linkend='configProblemResolver-BreakHoldScore'><literal>Aptitude::ProblemResolver::BreakHoldScore</literal></link>).
	  </para>
	</note>

	<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' width='100%' scalefit='1'/>
	    </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)]
















[1(1)/...] Suggest 2 keeps
e: Examine  !: Apply  .: Next  ,: Previous</screen>
	    </textobject>
	  </mediaobject>
	</screenshot>

	<para>
	  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 generate 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 generate.  At any time, you can select the
	  last generated solution by pressing <keycap>&gt;</keycap>,
	  and the first generated solution by pressing
	  <keycap>&lt;</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>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/solution-story-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	    </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
  --\ 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





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='secDependencyResolutionCosts'>
        <title>Costs in the interactive dependency resolver</title>

        <section id='secDependencyResolutionCostsAndCostComponents'>
          <title>Costs and cost components</title>

          <para>
            The <firstterm>cost</firstterm> of a solution produced by
            the interactive dependency resolver is a value that
            &aptitude; uses to determine how <quote>bad</quote> that
            solution is.  Solutions that are <quote>better</quote> are
            always displayed before solutions that are
            <quote>worse</quote>.  The cost of solutions is defined in
            the configuration option <link
            linkend='configProblemResolver-SolutionCost'><literal>Aptitude::ProblemResolver::SolutionCost</literal></link>.
          </para>

          <para>
            Some typical costs are shown in <xref
            linkend='exampleResolverCosts'/>.
          </para>

          <example id='exampleResolverCosts'>
            <title>Sample resolver costs</title>

            <para>
              The default cost, sorting solutions by their <link
              linkend='secDependencyResolutionCostsSafetyCosts'>safety
              cost</link>, then by their apt pin priority:
            </para>

            <screen>safety, priority</screen>

            <para>
              Remove as few packages as possible, then cancel as few
              actions as possible:
            </para>

            <screen>removals, canceled-actions</screen>

            <para>
              Sort solutions by the number of packages they remove
              <emphasis>plus</emphasis> twice the number of actions
              they cancel.
            </para>

            <screen>removals + 2 * canceled-actions</screen>
          </example>

          <para>
            As can be seen from the above examples, a cost is not
            necessarily a single number.  In fact, a cost consists of
            one or more <firstterm>cost components</firstterm>, each
            of which is a number associated with the solution.  When
            sorting solutions, the resolver examines cost components
            in order, proceeding to later components only if the
            earlier ones are equal.  For instance, in the cost
            <quote><literal>removals,
            canceled-actions</literal></quote>, solutions with fewer
            removals always appear before solutions with more
            removals, regardless of how many canceled actions they
            have.  However, solutions with the same number of removals
            are sorted so that solutions with fewer canceled actions
            appear first.
          </para>

          <para>
            Cost components come in two flavors:
            <emphasis>basic</emphasis> cost components and
            <emphasis>compound</emphasis> cost components.
          </para>

          <para>
            Basic components simply name some property of the
            solution, such as
            <quote><literal>upgrades</literal></quote> or
            <quote><literal>removals</literal></quote>.  A list of
            built-in basic components provided by &aptitude; can be
            found in <xref linkend='tableBasicCostComponents'/>.  You
            can also create your own cost components using the
            <literal>add-to-cost-component</literal> and
            <literal>raise-cost-component</literal> hints; see <xref
            linkend='secDependencyResolutionHints'/> for details.
          </para>

          <para>
            Each basic component is either a
            <emphasis>counter</emphasis> or a
            <emphasis>level</emphasis>.  Counters count how many of a
            solution's actions meet some condition (such as removing
            packages or installing new packages), while levels
            associate a number with each action and compute the
            highest number associated with any action in the solution.
          </para>

          <table id='tableBasicCostComponents'>
            <title>Basic cost components</title>

            <tgroup cols='3'>
              <thead>
                <row>
                  <entry>Name</entry>
                  <entry>Type</entry>
                  <entry>Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry><literal>broken-holds</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of holds that the solution
                    breaks, if the resolver is allowed to break holds
                    (<link
                    linkend='configProblemResolver-Allow-Break-Holds'><literal>Aptitude::ProblemResolver::Allow-Break-Holds</literal></link>).
                  </entry>
                </row>

                <row>
                  <entry><literal>canceled-actions</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of pending actions that the
                    solution cancels (keeping packages at their
                    current version).
                  </entry>
                </row>

                <row>
                  <entry><literal>installs</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of packages that the solution
                    installs.
                  </entry>
                </row>

                <row>
                  <entry><literal>non-default-versions</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of versions that the solution
                    installs or upgrades from non-default sources.
                  </entry>
                </row>

                <row>
                  <entry><literal>priority</literal></entry>
                  <entry>Level</entry>
                  <entry>
                    A value that increases as the apt pin priority of
                    a version decreases.  Specifically, this is
                    computed by negating the pin priority (so, e.g.,
                    if the pin priority is 500, this component will
                    compute -500).
                  </entry>
                </row>

                <row>
                  <entry><literal>removals</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of packages that the solution
                    removes.
                  </entry>
                </row>

                <row>
                  <entry><literal>removals-of-manual</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of manually installed packages
                    that the solution removes.
                  </entry>
                </row>

                <row>
                  <entry><literal>safety</literal></entry>
                  <entry>Level</entry>
                  <entry>
                    A broad heuristic that increases as actions become
                    less <quote>safe</quote>; see <xref
                    linkend='secDependencyResolutionCostsSafetyCosts'/>
                    for details.
                  </entry>
                </row>

                <row>
                  <entry><literal>upgrades</literal></entry>
                  <entry>Counter</entry>
                  <entry>
                    Counts the number of packages that the solution
                    upgrades.
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para>
            Compound components are built by combining the values of
            basic components.  For instance, <literal>removals +
            canceled-actions</literal> adds the components
            <literal>removal</literal> and
            <literal>canceled-actions</literal>, resulting in a
            component that counts the number of removals
            <emphasis>and</emphasis> canceled actions.  Compound
            components combine counters by adding them together and
            levels by taking their maximum value, as shown in <xref
            linkend='figureCompoundCostComponents'/>.
          </para>

          <note>
            <para>
              It is an error to add two levels, or to take the maximum
              of two counters, or to combine levels and counters in
              any way.  For instance, the costs <literal>removals +
              safety</literal> and <literal>max(upgrades,
              installs)</literal> will be treated as errors and
              ignored by the resolver.<footnote><para>This limit was
              imposed because more complex cost structures could make
              it difficult to optimize the resolver.  Future versions
              of the program might remove some of the restrictions if
              they turn out to be unnecessary.</para></footnote>
            </para>
          </note>

          <figure id='figureCompoundCostComponents'>
            <title>Syntax of compound cost components</title>

            <!-- Using "informalexample" to get sane titles for the
                 synopses without using two separate figures. -->
            <informalexample>
              <para>
                Add two or more basic costs:
              </para>
              <synopsis>
                <literal><optional><replaceable>scale1</replaceable></optional>*<replaceable>cost1</replaceable> + <optional><replaceable>scale2</replaceable></optional>*<replaceable>cost2</replaceable> + ...</literal>
              </synopsis>

              <para>
                Take the maximum value of two or more basic costs:
              </para>
              <synopsis>
                <literal>max(<optional><replaceable>scale1</replaceable></optional>*<replaceable>cost1</replaceable>, <optional><replaceable>scale2</replaceable></optional>*<replaceable>cost2</replaceable>, ...)</literal>
              </synopsis>
            </informalexample>
          </figure>

          <para>
            Note that each individual basic component can be
            multiplied by a scaling factor before it is combined with
            other components.  This can be used to control the
            trade-offs that the resolver makes between costs.  For
            instance, a cost of <literal>2*removals +
            3*upgrades</literal> says that three removals are exactly as
            <quote>bad</quote> as two upgrades.  Solutions that
            contain four removals and one upgrade will be considered
            equivalent to solutions containing one removal and three
            upgrades, since both have a cost of eleven.
          </para>
        </section>

        <section id='secDependencyResolutionCostsSafetyCosts'>
          <title>Safety costs</title>

          <figure id='figureSafetyCostLevels'>
            <title>Safety cost levels</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref='images/safety-cost-level-diagram.png'/>
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            The <literal>safety</literal> cost component is a
            heuristic estimate of how <quote>safe</quote> or
            <quote>unsafe</quote> a solution is.  Safety costs can be
            thought of as a way of dividing solutions into several
            numbered <quote>levels</quote>, where <quote>less
            safe</quote> levels are given higher numbers.  <xref
            linkend='figureSafetyCostLevels'/> shows how this works
            with &aptitude;'s default settings.
          </para>

          <tip>
            <para>
              Safety cost levels are just one way to control the order
              in which dependency solutions are returned.  See <xref
              linkend='secDependencyResolutionCosts'/> for a full
              description of how to change the order in which
              &aptitude; sorts solutions.
            </para>
          </tip>

          <para>
            By default, &aptitude; initializes the resolver with a
            <quote>reasonable</quote> set of safety cost levels.  They
            are:
          </para>

          <table id='tableDefaultSafetyCostLevels'>
            <title>Default safety cost levels</title>

            <tgroup cols='3'>
              <thead>
                <row>
                  <entry>Cost level</entry>
                  <entry>Description</entry>
                  <entry>Configuration option</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>10,000</entry>
                  <entry>
                    Solutions that include only <quote>safe</quote>
                    actions (installing the default target for a
                    package or keeping a package at its current
                    version) and package removals.
                  </entry>
                  <entry><literal><link linkend='configProblemResolver-Safe-Level'>Aptitude::ProblemResolver::Safe-Level</link></literal>, <literal><link linkend='configProblemResolver-Remove-Level'>Aptitude::ProblemResolver::Remove-Level</link></literal></entry>
                </row>

                <row>
                  <entry>20,000</entry>
                  <entry>
                    The solution that cancels all the user's actions.
                  </entry>
                  <entry><literal><link linkend='configProblemResolver-Keep-All-Level'>Aptitude::ProblemResolver::Keep-All-Level</link></literal></entry>
                </row>

                <row>
                  <entry>40,000</entry>
                  <entry>
                    Solutions that break holds set by the user or
                    install forbidden versions.
                  </entry>
                  <entry><literal><link linkend='configProblemResolver-Break-Hold-Level'>Aptitude::ProblemResolver::Break-Hold-Level</link></literal></entry>
                </row>

                <row>
                  <entry>50,000</entry>
                  <entry>
                    Solutions that install packages from non-default
                    versions (such as
                    <quote><literal>experimental</literal></quote>,
                    for instance).
                  </entry>
                  <entry><literal><link linkend='configProblemResolver-Non-Default-Level'>Aptitude::ProblemResolver::Non-Default-Level</link></literal></entry>
                </row>

                <row>
                  <entry>60,000</entry>
                  <entry>
                    Solutions that remove Essential packages.
                  </entry>
                  <entry><literal><link linkend='configProblemResolver-Remove-Essential-Level'>Aptitude::ProblemResolver::Remove-Essential-Level</link></literal></entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para>
            If a solution qualifies for several safety cost levels, it
            will be placed in the highest one, that is, the one that
            appears last.  For example, a solution that upgrades one
            package to its default version and breaks a hold on a
            second package will be placed at level 40,000.  You can
            adjust the levels of individual versions using resolver
            hints; see <xref linkend='secDependencyResolutionHints'/>
            for details.  The default levels are illustrated in <xref
            linkend='figureSafetyCostLevels'/>.
          </para>
        </section>
      </section>

      <section id='secDependencyResolutionConfiguration'>
	<title>Configuring the interactive dependency resolver</title>

	<section id='secDependencyResolutionHints'>
	  <title>Configuring resolver hints</title>

	  <para>
	    To improve the quality of the dependency solutions that
	    you receive, you can provide hints to the interactive
	    dependency resolver.  These hints can alter the priorities
	    of the resolver, biasing it more strongly in favor of one
	    version or package, or they can be used to
	    <quote>pre-load</quote> the resolver with rejections and
	    approvals, as if you had entered the resolver and manually
	    rejected or approved various versions.
	  </para>

	  <para>
	    Hints are stored in the &apt; configuration file,
	    <filename>/etc/apt/apt.conf</filename>, in the
	    configuration group <quote><literal><link
	    linkend='configProblemResolver-Hints'>Aptitude::ProblemResolver::Hints</link></literal></quote>
	    (see <xref linkend='secConfigFile'/> for details on the
	    configuration file).
	  </para>

	  <para>
	    Each resolver hint consists of an
	    <replaceable>action</replaceable>, a
	    <replaceable>target</replaceable>, and an optional
	    <replaceable>version</replaceable>.  A hint is written
	    like this: <literal>"<replaceable>action</replaceable>
	    <replaceable>target</replaceable>
	    <optional><replaceable>version</replaceable></optional>"</literal>.
	    To apply a resolver hint, &aptitude; locates one or more
	    packages using the value of
	    <replaceable>target</replaceable>, chooses one or more
	    versions of those packages using the value of
	    <replaceable>version</replaceable>, and finally performs
	    the given <replaceable>action</replaceable>.
	  </para>

	  <para>
	    The <replaceable>action</replaceable> field of a resolver
	    hint may be one of the following:
	  </para>

	  <orderedlist>
	    <listitem>
	      <para>
		<quote><literal>approve</literal></quote>: Approve the
		version, as if the command <link
		linkend='menuResolverApprove'>&resolver-approve;</link>
		had been invoked on it.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>reject</literal></quote>: Reject the
		version, as if the command <link
		linkend='menuResolverReject'>&resolver-reject;</link>
		had been invoked on it.
	      </para>
	    </listitem>

            <listitem id='hintDiscard'>
              <para>
                <quote><literal>discard</literal></quote>: Discard
                every solution containing the version.  Differs from
                <quote><literal>reject</literal></quote> in that it is
                not visible to the user and cannot be modified
                interactively.
              </para>
            </listitem>

	    <listitem>
	      <para>
		<quote><literal>increase-safety-cost-to
		<replaceable>number</replaceable></literal></quote>:
		increase the safety cost of any solution that contains
		the version to <replaceable>number</replaceable>; if
		its safety cost is already higher than
		<replaceable>number</replaceable>, this hint has no
		effect.  The safety cost can be used (and is used by
		default) to control the order in which solutions
		appear; see <xref
		linkend='secDependencyResolutionCostsAndCostComponents'/>
		and <xref
		linkend='secDependencyResolutionCostsSafetyCosts'/>
		for details.
	      </para>

	      <para>
		Several special cost levels can be chosen by name:

		<orderedlist>
                  <listitem>
                    <para>
                      <literal>conflict</literal>,
                      <literal>discard</literal>: instead of changing
                      the safety cost, discard solutions containing
                      the version as if the <quote><link
                      linkend='hintDiscard'><literal>discard</literal></link></quote>
                      hint had been applied.
                    </para>
                  </listitem>

		  <listitem>
		    <para>
		      <literal>maximum</literal>: the highest safety
		      cost.
		    </para>
		  </listitem>

		  <listitem>
		    <para>
		      <literal>minimum</literal>: the lowest safety
		      cost. All searches start at this cost, so
		      <quote>increasing</quote> a version to this cost
		      has no effect.  However, this value can also be
		      used when adjusting the predefined cost levels:
		      for instance, setting <link
		      linkend='configProblemResolver-Remove-Level'><literal>Aptitude::ProblemResolver::Remove-Level</literal></link>
		      to <quote><literal>minimum</literal></quote>
		      will cause removed packages to have no effect on
		      the safety cost of a solution.
		    </para>
		  </listitem>
		</orderedlist>
	      </para>

	      <note>
		<para>
		  The <literal>increase-safety-cost-to</literal> hint
		  is applied <emphasis>in addition</emphasis> to any
		  default safety cost that is due to the selected
		  action.  For instance, a hint that increases the
		  safety cost of <quote>install
		  <systemitem>hal</systemitem> from
		  <systemitem>experimental</systemitem></quote> to
		  15,000 will have no effect, because that action
		  already has a safety cost of 50,000 (assuming that
		  this version of <systemitem>hal</systemitem> is not
		  the default candidate version).
		</para>
	      </note>
	    </listitem>

	    <listitem>
	      <para>
		<quote><replaceable>number</replaceable></quote>: add
		the given <replaceable>number</replaceable> to the
		version's <replaceable>score</replaceable>, biasing
		the resolver in favor of it or (with a negative
		number) away from it.  For instance, the hint
		<literal>200 emacs</literal> adds 200 to the score of
		<literal>emacs</literal>, whereas the hint
		<literal>-10 emacs</literal> subtracts 10 from its
		score.
	      </para>
	    </listitem>
	  </orderedlist>

	  <para>
	    If <replaceable>target</replaceable> field of a resolver
	    hint contains a question mark
	    (<quote><literal>?</literal></quote>) or tilde
	    (<quote><literal>~</literal></quote>), it is considered to
	    be a search pattern and all matching package versions are
	    considered.  Otherwise, it is considered to be the name of
	    a package to select.  So the target
	    <quote><literal>g++</literal></quote> will select only the
	    <literal>g++</literal> package, but the target
	    <quote><literal>?section(non-free)</literal></quote> will
	    select any package in the <literal>non-free</literal>
	    section.  See <xref linkend='secSearchPatterns'/> for more
	    information on search patterns.
	  </para>

	  <para>
	    If the <replaceable>version</replaceable> field is not
	    present, then all versions of the package are affected by
	    the hint.  Otherwise, it may have any of the following
	    forms:
	  </para>

	  <orderedlist>
	    <listitem>
	      <para>
		<quote><literal>/<replaceable>archive</replaceable></literal></quote>:
		the hint only affects versions that are available in
		the given <replaceable>archive</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>&lt;<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		less than <replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>&lt;=<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		less than or equal to
		<replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>=<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		<replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>&lt;&gt;<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		not <replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>&gt;=<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		greater than or equal to
		<replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>&gt;<replaceable>version</replaceable></literal></quote>:
		the hint only affects versions whose version number is
		greater than <replaceable>version</replaceable>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><literal>:UNINST</literal></quote>: instead of
		affecting any of the versions of
		<replaceable>target</replaceable>, the hint affects
		the decision to remove
		<replaceable>target</replaceable>.  For instance,
		<quote><literal>reject aptitude
		:UNINST</literal></quote> will prevent the resolver
		from attempting to remove &aptitude;.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote><replaceable>version</replaceable></quote>: the
		hint only affects versions whose version number is
		<replaceable>version</replaceable>.
	      </para>
	    </listitem>
	  </orderedlist>
	</section>
      </section>
    </section>

    <section id='secSearchPatterns'>
      <title>Search patterns</title>

      <para>
	When you search for a package or set a display limit in
	&aptitude;, the string you enter is known as a <quote>search
	pattern</quote>.  While the most basic usage of search
	patterns is to match packages by name, &aptitude; allows you
	to create much more complex searches.  In addition to the
	visual interface, some command-line operations can use search
	patterns; see <xref linkend='secReference'/> for details.
      </para>

      <para>
	A search pattern consists of one or more conditions (sometimes
	known as <quote>terms</quote>); packages match the pattern if
	they match all of its terms.  Terms generally start with a
	question mark (<quote>?</quote>), followed by the name of the
	match term, which describes the search that the term performs:
	for instance, the term &Sname; matches package names, while
	the term &Sversion; matches package versions.  Finally, any
	additional parameters to the search term are placed in
	parentheses (see the documentation of individual terms for
	details of what each term's parameters mean).
      </para>

      <note>
	<para>
	  Text with no leading <quote>?</quote> also forms a search
	  pattern: &aptitude; will treat each word (or quoted string)
	  as the argument to a &Sname; pattern, which searches for a
	  package whose name matches the text when the text is
	  interpreted as a regular expression.
	</para>
      </note>

      <warning>
	<para>
	  The behavior of &aptitude; when given a search pattern without
	  a leading <quote>?</quote> (or <quote>~</quote>) is provided
	  as a convenience for interactive use and will change in
	  future releases; scripts that invoke
	  <literal>aptitude</literal> should explicitly name the
	  search strategy they want to use.  That is, scripts should
	  search for <quote><literal>&Sname;(coq)</literal></quote>
	  rather than <quote><literal>coq</literal></quote>).
	</para>
      </warning>

      <section>
	<title>Searching for strings</title>

	<para>
	  Many search terms take a string as a parameter and match it
	  against one or more fields of a package.  Strings can be
	  entered either with or without double quotes
	  (<quote><literal>"</literal></quote>), so
	  <quote><literal>&Sname;(scorch)</literal></quote> and
	  <quote><literal>&Sname;("scorch")</literal></quote> will
	  perform the same search.  If you enter a search string using
	  double quotes, you can include a literal double-quote in the
	  search string by placing a backslash
	  (<quote><literal>\</literal></quote>) immediately before it:
	  for instance,
	  <quote><literal>&Sdescription;("\"easy\"")</literal></quote>
	  will match any package whose description contains the string
	  <quote><literal>"easy"</literal></quote>.
	</para>

	<para>
	  If you enter a <quote>bare</quote> string, one not
	  surrounded by double quotes, then &aptitude; will consider
	  the string to have <quote>ended</quote> when it encounters
	  the closing parenthesis or the comma before a second
	  argument to the search term.
	  <footnote>
	    <para>
	      &aptitude; will only treat the comma as special if there
	      is a second argument, so (for instance)
	      <quote><literal>&Sname;(apt,itude)</literal></quote>
	      searches for the string
	      <quote><literal>apt,itude</literal></quote> in the
	      <literal>Name</literal> field of packages.
	    </para>

	    <para>
	      While this behavior is well-defined, it may be
	      surprising; I recommend using quoted strings for any
	      pattern that contains characters that could have a
	      special meaning.
	    </para>
	  </footnote>
	  To remove the special meaning of these characters, place a
	  tilde (<quote><literal>~</literal></quote>) directly before
	  them.  For instance,
	  <quote><literal>&Sdescription;(etc))</literal></quote> is a
	  syntax error, because the first
	  <quote><literal>)</literal></quote> ends the &Sdescription;
	  term, and the second <quote><literal>)</literal></quote>
	  does not correspond to any
	  <quote><literal>(</literal></quote>.  In contrast,
	  <quote><literal>&Sdescription;(etc~))</literal></quote>
	  matches any package whose description contains the text
	  <quote><literal>etc)</literal></quote>.  There are
	  additional considerations if you are using the shorthand
	  notation for a term; see <xref
	  linkend='secSearchShorthand'/> for details.
	</para>

	<para>
	  Most textual searches (for package names, descriptions, etc)
	  are performed using case-insensitive <ulink
	  url='http://web.archive.org/web/20060719181658/http://sitescooper.org/tao_regexps.html'>regular
	  expressions</ulink>.  A regular expression will match
	  against a field if any portion of the field matches the
	  expression; for instance,
	  <quote><literal>ogg[0-9]</literal></quote> will match
	  <quote><literal>libogg5</literal></quote>,
	  <quote><literal>ogg123</literal></quote>, and
	  <quote><literal>theogg4u</literal></quote>.
	  Some characters have a special meaning within regular
	  expressions
	  <footnote>
	    <para>
	      Characters with a special meaning include:
	      <quote><literal>+</literal></quote>,
	      <quote><literal>-</literal></quote>,
	      <quote><literal>.</literal></quote>,
	      <quote><literal>(</literal></quote>,
	      <quote><literal>)</literal></quote>,
	      <quote><literal>|</literal></quote>,
	      <quote><literal>[</literal></quote>,
	      <quote><literal>]</literal></quote>,
	      <quote><literal>^</literal></quote>,
	      <quote><literal>$</literal></quote>, and
	      <quote><literal>?</literal></quote>.  Note that some of
	      these are also &aptitude; metacharacters, so if you want
	      to type (for instance) a literal
	      <quote><literal>|</literal></quote>, it must be
	      double-escaped:
	      <quote><literal>&Sdescription;(\~|)</literal></quote>
	      will match packages whose description contains a
	      vertical bar character
	      (<quote><literal>|</literal></quote>).
	    </para>
	  </footnote>
	  , so if you want to match them in searches you need to
	  backslash-escape them: for instance, to find
	  <quote><literal>g++</literal></quote>, you should use the
	  pattern <quote><literal>g\+\+</literal></quote>.
	</para>

	<para>
	  The characters <quote><literal>!</literal></quote> and
	  <quote><literal>|</literal></quote> have special meanings
	  within search patterns.  In order to include these
	  characters in an unquoted string, you can place a tilde
	  (<quote><literal>~</literal></quote>) directly before them.
	  For instance, to match packages whose description contains
	  either <quote>grand</quote> or <quote>oblique</quote>, use
	  the pattern
	  <quote><literal>&Sdescription;(grand~|oblique)</literal></quote>.
	  However, you will probably find it more convenient to simply
	  use a quoted string in these cases:
	  <quote><literal>&Sdescription;("grand|oblique")</literal></quote>.
	</para>
      </section>

      <section id='secSearchShorthand'>
	<title>Shorthand for search terms</title>

	<para>
	  Some search terms can be written using <quote>short</quote>
	  forms, which consist of a tilde
	  (<quote><literal>~</literal></quote>) followed by a single
	  character that identifies the term, and finally the
	  arguments (if any) to the term.  For instance, the short
	  form of <literal>&Sname;(aptitude)</literal> is <literal>~n
	  aptitude</literal>.
	</para>

	<para>
	  When writing a term using its short form, tilde characters
	  and <quote>whitespace</quote> -- that is, space characters,
	  tabs, and so on -- will break the term off and start a new
	  term.  For instance, <quote><literal>~mDaniel
	  Burrows</literal></quote> will match any package whose
	  maintainer field contains
	  <quote><literal>Daniel</literal></quote> and whose name
	  contains <quote><literal>Burrows</literal></quote>, while
	  <quote><literal>~i~napt</literal></quote> matches installed
	  packages whose name contains <literal>apt</literal>.  To
	  include whitespace characters in the search expression, you
	  can either place a tilde in front of it (as in
	  <literal>Daniel~ Burrows</literal>) or place quotation marks
	  around it (as in <literal>"Debian Project"</literal> or even
	  <literal>Debian" "Project</literal>).  Inside a quoted
	  string, the backslash character (<quote>\</quote>) can be
	  used to cancel the special meaning of the quotation mark:
	  for instance, <literal>~d"\"email"</literal> will match any
	  package whose description contains a quotation mark followed
	  immediately by <literal>email</literal>.
	  <footnote>
	    <para>
	      The backslash escapes <literal>\\</literal>,
	      <literal>\n</literal>, and <literal>\t</literal> are also
	      available.
	    </para>
	  </footnote>
	</para>

	<note>
	  <para>
	    Question marks (<quote><literal>?</literal></quote>) will
	    <emphasis>not</emphasis> end the short form of a term,
	    even if they are followed by the name of a search term.
	    For instance,
	    <quote><literal>~napt?priority(required)</literal></quote>
	    will match all packages whose name matches the regular
	    expression
	    <quote><literal>apt?priority(required)</literal></quote>.
	    To combine a short query term with a search term specified
	    by name, add one or more spaces between the two terms, as
	    in
	    <quote><literal>~napt&nbsp;?priority(required)</literal></quote>,
	    or place quotation marks around the text (if any)
	    following the short form of a term, as in
	    <quote><literal>~n"apt"?priority(required)</literal></quote>.
	  </para>
	</note>

	<para>
	  <xref linkend='tableSearchTermQuickGuide'/> lists the short
	  form of each search term.
	</para>
      </section>

      <section>
	<title>Searches and versions</title>

	<para>
	  By default, a pattern matches a package if any version of
	  the package matches the pattern.  However, some patterns
	  will restrict their sub-patterns to only match against some
	  versions of a package.  For instance, the search term
	  <literal>&Sdepends;(<replaceable>pattern</replaceable>)</literal>
	  will select any package that depends on a package matching
	  <replaceable>pattern</replaceable>.  However,
	  <replaceable>pattern</replaceable> will only be checked
	  against the versions of the package that actually satisfy a
	  dependency.  This means that if <literal>foo</literal>
	  depends on <literal>bar (>= 3.0)</literal> and versions
	  <literal>2.0</literal>, <literal>3.0</literal>, and
	  <literal>4.0</literal> of <literal>bar</literal> are
	  available, then in the search pattern
	  <literal>&Sdepends;(&Sversion;(2\.0))</literal>, only
	  versions <literal>3.0</literal> and <literal>4.0</literal>
	  will be tested against <literal>&Sversion;(2\.0)</literal>,
	  and hence <literal>foo</literal> will not be found by this
	  search.
	</para>

	<para>
	  It matters which versions are checked because, as in the
	  example above, some patterns will match one version but not
	  another.  For instance, the pattern &Sinstalled; will only
	  match the version of the package (if any) that is currently
	  installed.  Similarly, the pattern
	  <literal>&Smaintainer;(<replaceable>maintainer</replaceable>)</literal>
	  will only match versions that have the given
	  <replaceable>maintainer</replaceable>.  Normally all
	  versions of a package have the same maintainer, but this is
	  not always the case; in fact, any search pattern that
	  examines the fields of a package (other than its name, of
	  course) will behave this way, because all the fields of a
	  package can change between versions.
	</para>

	<para>
	  To test a pattern against all the versions of a package,
	  even if the pattern would normally be tested against only
	  some of the versions, use the &Swiden; term.  For instance,
	  <literal>&Sdepends;(&Swiden;(&Sversion;(2\.0)))</literal>
	  will match any package <replaceable>A</replaceable> that
	  depends on a package <replaceable>B</replaceable>, where
	  <replaceable>B</replaceable> has a version matching
	  <literal>2.0</literal>, regardless of whether that version
	  actually satisfies <replaceable>A</replaceable>'s
	  dependency.  On the other hand, the &Snarrow; term restricts
	  the versions that its sub-pattern is matched against:
	  <literal>&Snarrow;(&Sinstalled;,
	  &Sdepends;(&Sversion;(ubuntu)))</literal> will match any
	  package whose installed version has a dependency that can be
	  satisfied by a package whose version string contains
	  <quote><literal>ubuntu</literal></quote>.
	</para>

	<note>
	  <para>
	    There is a subtle, but important, distinction between
	    matching a pattern against a package, and matching it
	    against all the versions of that package.  When a pattern
	    is matched against a package, each of its terms is matched
	    against the package, and so each term will match if
	    <emphasis>any</emphasis> version of the package matches.
	    In contrast, when a pattern is matched against each
	    version of a package, it will successfully match if it
	    matches when all its terms are matched against the
	    <emphasis>same</emphasis> version of the package.
	  </para>

	  <para>
	    For example: suppose that version <literal>3.0-1</literal>
	    of the package <literal>aardvark</literal> is installed,
	    but that version <literal>4.0-1</literal> is available.
	    Then the search expression
	    <literal>&Sversion;(4\.0-1)&Sinstalled;</literal> matches
	    <literal>aardvark</literal>, because
	    <literal>&Sversion;(4\.0-1)</literal> matches against
	    version <literal>4.0-1</literal> of
	    <literal>aardvark</literal>, while &Sinstalled; matches
	    against version <literal>3.0-1</literal>.  On the other
	    hand, this expression <emphasis>does not</emphasis> match
	    against all the versions of <literal>aardvark</literal>,
	    because no single version is installed and also has a
	    version number of <literal>4.0-1</literal>.
	  </para>
	</note>

	<!-- TODO: I'd like to have a table of how matchers restrict
             their sub-matchers, but I can't figure out how to
             succinctly describe some matchers. -->
      </section>

      <section id='secExplicitMatchers'>
	<title>Explicit search targets</title>

	<para>
	  Some particularly complex searches can be expressed in
	  &aptitude; using <firstterm>explicit targets</firstterm>.
	  In normal search expressions, there is no way to refer to
	  the package or version that is currently being tested.  For
	  instance, suppose that you want to search for all packages
	  <replaceable>P</replaceable> that depend on a second package
	  <replaceable>Q</replaceable> such that
	  <replaceable>Q</replaceable> recommends
	  <replaceable>P</replaceable>.  Clearly you need to start out
	  with a <literal>&Sdepends;(...)</literal> term.  But the
	  term filling in the <literal>...</literal> needs to somehow
	  select packages that are identical to the one being matched
	  against <literal>&Sdepends;</literal>.  When describing the
	  goal above, I dealt with this by giving the packages names,
	  calling them <replaceable>P</replaceable> and
	  <replaceable>Q</replaceable>; terms with explicit targets
	  do exactly the same thing.
	  <footnote>
	    <para>
	      Astute readers will note that this is essentially a way
	      to explicitly name the variable in the &lambda;-terms
	      corresponding to the term.  A typical term would
	      have the form <quote>&lambda;
	      <replaceable>x</replaceable>
	      . name-equals(<replaceable>x</replaceable>,
	      <replaceable>pattern</replaceable>)</quote>; giving this
	      an explicit target makes <replaceable>x</replaceable>
	      visible in the search language.
	    </para>
	  </footnote>
	</para>

	<para>
	  An explicit target is introduced by the &Sfor; term:
	</para>

	<figure>
	  <title>Syntax of the &Sfor; term</title>

	  <synopsis><literal>?for <replaceable>variable</replaceable>: <replaceable>pattern</replaceable></literal></synopsis>
	</figure>

	<para>
	  This behaves exactly like <replaceable>pattern</replaceable>,
	  but <replaceable>variable</replaceable> can be used within
	  <replaceable>pattern</replaceable> to refer to the package or
	  version that <replaceable>pattern</replaceable> is being
	  matched against.  You can use
	  <replaceable>variable</replaceable> in two ways:
	</para>

	<orderedlist>
	  <listitem>
	    <para>
	      The term &Sequal; will match exactly the package or
	      version indicated by the given variable.  Specifically:
	      if the corresponding &Sfor; term is limited to a
	      particular version, then &Sequal; will match either that
	      version (if &Sequal; is limited) or the whole package;
	      otherwise it will match any version of the package.
	    </para>

	    <para>
	      See <xref linkend='exampleSearchEqual'/> for an example
	      of how to use &Sequal;.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The term
	      <literal>&Sbind;(<replaceable>variable</replaceable>,
	      <replaceable>pattern</replaceable>)</literal> will match
	      any package or version if the value of
	      <replaceable>variable</replaceable> matches against
	      <replaceable>pattern</replaceable>.
	    </para>

	    <para>
	      For <literal>?</literal>-style terms, a shorthand
	      form is available.  The expression
	      <literal>&Sbind;(<replaceable>variable</replaceable>,
	      ?<replaceable>term</replaceable><optional>(<replaceable>args</replaceable>)</optional>)</literal>
	      can be replaced by
	      <literal>?<replaceable>variable</replaceable>:<replaceable>term</replaceable>(<replaceable>args</replaceable>)</literal>.
	    </para>

	    <para>
	      See <xref linkend='exampleSearchBind'/> for an example
	      of how to use <literal>?bind</literal>.
	    </para>
	  </listitem>
	</orderedlist>
      </section>

      <section id='secSearchTermReference'>
	<title>Search term reference</title>

	<para>
	  <xref linkend='tableSearchTermQuickGuide'/> provides a brief
	  summary of all the search terms provided by &aptitude;.  A
	  full description of each term can be found <link
	  linkend='searchTermReferenceList'>below</link>.
	</para>

	<table id='tableSearchTermQuickGuide'>
	  <title>Quick guide to search terms</title>

	  <tgroup cols='3'>
	    <thead>
	      <row>
		<entry>Long form</entry>
		<entry>Short form</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry>
		  <literal>&Sequal;<replaceable>variable</replaceable></literal>
		</entry>
		<entry/>
		<entry>
		  Select the package bound to
		  <replaceable>variable</replaceable>; see <xref
		  linkend='secExplicitMatchers'/>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Snot;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>!<replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select any package that does not match
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Saction;(<replaceable>action</replaceable>)</literal>
		</entry>
		<entry>~a<replaceable>action</replaceable></entry>
		<entry>
		  Select packages that have been marked for the given
		  <replaceable>action</replaceable> (e.g.,
		  <quote><literal>install</literal></quote> or
		  <quote><literal>upgrade</literal></quote>).
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Sall-versions;(<replaceable>pattern</replaceable>)</literal>
		</entry>
		<entry/>
		<entry>
		  Select packages whose versions all match
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Sand;(<replaceable>pattern1</replaceable>, <replaceable>pattern2</replaceable>)</literal>
		</entry>
		<entry><replaceable>pattern1</replaceable> <replaceable>pattern2</replaceable></entry>
		<entry>
		  Select any package that matches both
		  <replaceable>pattern1</replaceable> and
		  <replaceable>pattern2</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sany-version;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Select packages for which at least one version
		  matches <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Sarchitecture;(<replaceable>architecture</replaceable>)</literal>
		</entry>
		<entry>~r<replaceable>architecture</replaceable></entry>
		<entry>
		  Select packages for the given architecture (such as
		  <quote><literal>amd64</literal></quote>, or
		  <quote><literal>all</literal></quote>).  Special values:
		  <literal>native</literal> and <literal>foreign</literal>.
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Sarchive;(<replaceable>archive</replaceable>)</literal>
		</entry>
		<entry>
		  <literal>~A<replaceable>archive</replaceable></literal>
		</entry>
		<entry>
		  Select packages from the given archive (such as
		  <quote><literal>unstable</literal></quote>).
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sautomatic;</literal></entry>
		<entry><literal>~M</literal></entry>
		<entry>
		  Select packages that were automatically installed.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sbind;(<replaceable>variable</replaceable>, <replaceable>pattern</replaceable>)</literal></entry>
		<entry>
		  <literal>?<replaceable>variable</replaceable>:<replaceable>term-name</replaceable><optional>(<replaceable>args</replaceable>)</optional></literal>
		</entry>
		<entry>
		  Selects anything if
		  <replaceable>variable</replaceable> matches
		  <replaceable>pattern</replaceable>; see <xref
		  linkend='secExplicitMatchers'/>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sbroken;</literal></entry>
		<entry><literal>~b</literal></entry>
		<entry>
		  Select packages that have a broken dependency.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sbroken-type;</literal></entry>
		<entry><literal>~B<replaceable>depType</replaceable></literal></entry>
		<entry>
		  Select package that have a broken dependency of the
		  given <replaceable>depType</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sbroken-type-term;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~DB<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that have a broken dependency of the
		  given <replaceable>depType</replaceable> matching
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sbroken-reverse-dep;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~RB<option><replaceable>depType</replaceable>:</option><replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that a package matching
		  <replaceable>pattern</replaceable> declares a broken
		  dependency of type <replaceable>depType</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry>
		  <literal>&Sconflicts;(<replaceable>pattern</replaceable>)</literal>
		</entry>
		<entry><literal>~C<replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that conflict with a package
		  matching <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sconfig-files;</literal></entry>
		<entry><literal>~c</literal></entry>
		<entry>
		  Select packages that were removed but not purged.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sdep;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~D<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Match packages that declare a dependency of type
		  <replaceable>depType</replaceable> on a package
		  matching <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sdescription;(<replaceable>description</replaceable>)</literal></entry>
		<entry><literal>~d<replaceable>description</replaceable></literal></entry>
		<entry>
		  Select packages whose description matches
		  <replaceable>description</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sessential;</literal></entry>
		<entry><literal>~E</literal></entry>
		<entry>
		  Select essential packages, those with
		  <literal>Essential: yes</literal> in their control
		  files.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sexact-name;(<replaceable>name</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Select packages named
		  <replaceable>name</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sfalse;</literal></entry>
		<entry><literal>~F</literal></entry>
		<entry>
		  Select no packages.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sfor; <replaceable>variable</replaceable>: <replaceable>pattern</replaceable></literal></entry>
		<entry/>
		<entry>
		  Select packages that match
		  <replaceable>pattern</replaceable> with
		  <replaceable>variable</replaceable> bound to the
		  package being matched; see <xref
		  linkend='secExplicitMatchers'/>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sgarbage;</literal></entry>
		<entry><literal>~g</literal></entry>
		<entry>
		  Select packages that are not required by any manually
		  installed package.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sinstalled;</literal></entry>
		<entry><literal>~i</literal></entry>
		<entry>Select installed packages.</entry>
	      </row>

	      <row>
		<entry><literal>&Smaintainer;(<replaceable>maintainer</replaceable>)</literal></entry>
		<entry><literal>~m<replaceable>maintainer</replaceable></literal></entry>
		<entry>
		  Select packages maintained by
		  <replaceable>maintainer</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Smultiarch;(<replaceable>multiarch</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Select packages with a multi-arch capability of
		  <replaceable>multiarch</replaceable> (that is, either
		  <quote><literal>foreign</literal></quote>,
		  <quote><literal>same</literal></quote>,
		  <quote><literal>allowed</literal></quote>, or
		  <quote><literal>none</literal></quote>).
		</entry>
	      </row>

	      <row>
		<entry><literal>&Snarrow;(<replaceable>filter</replaceable>, <replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~S <replaceable>filter</replaceable> <replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages for which a single version matches
		  both <replaceable>filter</replaceable> and
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sname;(<replaceable>name</replaceable>)</literal></entry>
		<entry><literal>~n<replaceable>name</replaceable></literal>, <literal><replaceable>name</replaceable></literal></entry>
		<entry>
		  Select packages with the given <replaceable>name</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Snew;</literal></entry>
		<entry><literal>~N</literal></entry>
		<entry>
		  Select new packages.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sobsolete;</literal></entry>
		<entry><literal>~o</literal></entry>
		<entry>
		  Match installed packages that cannot be downloaded.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sor;(<replaceable>pattern1</replaceable>, <replaceable>pattern2</replaceable>)</literal></entry>
		<entry><literal><replaceable>pattern1</replaceable> | <replaceable>pattern2</replaceable></literal></entry>
		<entry>
		  Select packages that match
		  <replaceable>pattern1</replaceable>,
		  <replaceable>pattern2</replaceable>, or both.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sorigin;(<replaceable>origin</replaceable>)</literal></entry>
		<entry><literal>~O<replaceable>origin</replaceable></literal></entry>
		<entry>
		  Select packages with the given
		  <replaceable>origin</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sprovides;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~P<replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that provide a package matching
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Spriority;(<replaceable>priority</replaceable>)</literal></entry>
		<entry><literal>~p<replaceable>priority</replaceable></literal></entry>
		<entry>
		  Select packages with the given <replaceable>priority</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sreverse-dep;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~R<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that are the targets of a dependency
		  of type <replaceable>depType</replaceable> declared
		  by a package matching
		  <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sreverse-broken-dep;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~RB<option><replaceable>depType</replaceable>:</option><replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select packages that are the targets of a broken
		  dependency of type
		  <replaceable>depType</replaceable> declared by a
		  package matching <replaceable>pattern</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Ssection;(<replaceable>section</replaceable>)</literal></entry>
		<entry><literal>~s<replaceable>section</replaceable></literal></entry>
		<entry>
		  Select packages in the given <replaceable>section</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Ssource-package;(<replaceable>name</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Select packages whose source package name matches
		  the regular expression
		  <replaceable>name</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Ssource-version;(<replaceable>version</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Select packages whose source version matches the
		  regular expression <replaceable>version</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Stag;(<replaceable>tag</replaceable>)</literal></entry>
		<entry><literal>~G<replaceable>tag</replaceable></literal></entry>
		<entry>
		  Select packages that have the given debtags
		  <replaceable>tag</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sterm;(<replaceable>keyword</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Full-text search for packages that contain the given
		  <replaceable>keyword</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sterm-prefix;(<replaceable>keyword</replaceable>)</literal></entry>
		<entry/>
		<entry>
		  Full-text search for packages that contain a keyword
		  that begins with the given
		  <replaceable>keyword</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Strue;</literal></entry>
		<entry><literal>~T</literal></entry>
		<entry>
		  Select all packages.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Stask;(<replaceable>task</replaceable>)</literal></entry>
		<entry><literal>~t<replaceable>task</replaceable></literal></entry>
		<entry>
		  Select packages that are in the given
		  <replaceable>task</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Supgradable;</literal></entry>
		<entry><literal>~U</literal></entry>
		<entry>
		  Select packages that are installed and can be
		  upgraded.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Suser-tag;</literal></entry>
		<entry/>
		<entry>
		  Select packages that are marked with a user-tag
		  matching the regular expression
		  <replaceable>user-tag</replaceable>.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Sversion;(<replaceable>version</replaceable>)</literal></entry>
		<entry><literal>~V<replaceable>version</replaceable></literal></entry>
		<entry>
		  Select packages whose version matches
		  <replaceable>version</replaceable> (special values:
		  <literal>CURRENT</literal>,
		  <literal>CANDIDATE</literal>, and
		  <literal>TARGET</literal>).
		</entry>
	      </row>

	      <row>
		<entry><literal>&Svirtual;</literal></entry>
		<entry><literal>~v</literal></entry>
		<entry>
		  Select virtual packages.
		</entry>
	      </row>

	      <row>
		<entry><literal>&Swiden;(<replaceable>pattern</replaceable>)</literal></entry>
		<entry><literal>~W<replaceable>pattern</replaceable></literal></entry>
		<entry>
		  Select versions for which
		  <replaceable>pattern</replaceable> matches any version
		  of the corresponding package, discarding local
		  version restrictions.
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

      <variablelist id='searchTermReferenceList'>
	<varlistentry>
	  <term><replaceable>name</replaceable></term>

	  <listitem>
	    <para>
	      Matches packages whose names match the regular
	      expression <replaceable>name</replaceable>.  This is the
	      <quote>default</quote> search mode and is used for patterns that
	      don't start with <literal>~</literal>.
	    </para>

	    <note>
	      <para>
		To match packages whose names contain several
		different substrings, use the &Sname; term (described
		below); for instance,
		<quote><literal>&Sname;(apti)&Sname;(tude)</literal></quote>
		will match any package whose name contains
		<emphasis>both</emphasis>
		<quote><literal>apti</literal></quote> and
		<quote><literal>tude</literal></quote>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchEqual'>
	  <term><literal>?=<replaceable>variable</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages that correspond to the value of
	      <replaceable>variable</replaceable>, which must be bound
	      by an enclosing &Sfor;.  For instance, <literal>&Sfor; x:
	      &Sdepends;( &Srecommends;( ?=x ) )</literal> will match any
	      package <replaceable>x</replaceable> that depends on a
	      package which recommends <replaceable>x</replaceable>.
	    </para>

	    <para>
	      For instance, the following search expression matches
	      packages that conflict with themselves:
	    </para>

	    <example id='exampleSearchEqual'>
	      <title>
		Use of the <literal>?=</literal> term.
	      </title>

	      <para>
		<literal>
		  &Sfor; x: &Sconflicts;(?=x)
		</literal>
	      </para>
	    </example>

	    <para>
	      See <xref linkend='secExplicitMatchers'/> for more
	      information.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchNot'>
	  <term><literal>?not(<replaceable>pattern</replaceable>)</literal>, <literal>!<replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which do <emphasis>not</emphasis> match
	      the pattern <replaceable>pattern</replaceable>.  For
	      instance,
	      <quote><literal>?not(&Sbroken;)</literal></quote>
	      selects packages that are not <quote>broken</quote>.
	    </para>

	    <note>
	      <para>
		To include a <quote>!</quote> in a search string, it
		must be <quote>escaped</quote> by placing a tilde
		(<quote><literal>~</literal></quote>) in front of it;
		otherwise, &aptitude; will consider it to be part of a
		<literal>?not</literal> term.  For instance, to select
		packages whose description contains
		<quote><literal>extra!</literal></quote>, use
		<quote><literal>&Sdescription;(extra~!)</literal></quote>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchAnd'>
	  <term><literal>?and(<replaceable>pattern1</replaceable>, <replaceable>pattern2</replaceable>)</literal>, <replaceable>pattern1</replaceable> <replaceable>pattern2</replaceable></term>

	  <listitem>
	    <para>
	      Matches packages that match both
	      <replaceable>pattern1</replaceable> and
	      <replaceable>pattern2</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchOr'>
	  <term><literal>?or(<replaceable>pattern1</replaceable>, <replaceable>pattern2</replaceable>)</literal>, <literal><replaceable>pattern1</replaceable> | <replaceable>pattern2</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages that match either
	      <replaceable>pattern1</replaceable> or
	      <replaceable>pattern2</replaceable>.
	    </para>

	    <note>
	      <para>
		To use the character <quote>|</quote> in a regular expression, it
		must be <quote>escaped</quote> to prevent &aptitude; from creating
		an OR term from it: <quote><literal>~|</literal></quote>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>(<replaceable>pattern</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches <replaceable>pattern</replaceable>.  For instance,
	      <quote><literal>opengl (perl|python)</literal></quote>
	      matches any package whose name contains
	      <literal>opengl</literal>, and also contains either
	      <literal>perl</literal> or <literal>python</literal>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchAction'>
	  <term><literal>?action(<replaceable>action</replaceable>)</literal>, <literal>~a<replaceable>action</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages upon which the given
	      <replaceable>action</replaceable> is going to be
	      performed.  <replaceable>action</replaceable> can be
	      <quote><literal>install</literal></quote>,
	      <quote><literal>upgrade</literal></quote>,
	      <quote><literal>downgrade</literal></quote>,
	      <quote><literal>remove</literal></quote>,
	      <quote><literal>purge</literal></quote>,
	      <quote><literal>hold</literal></quote> (tests whether a
	      package has been placed on hold), or
	      <quote><literal>keep</literal></quote> (tests whether a
	      package will be unchanged).
	      <!-- Should I document more extensively what each option
	           does? -->
	    </para>

	    <para>
	      Note that this only tests whether an action is actually
	      queued up to be performed on a package, not whether it
	      <emphasis>could</emphasis> be performed.  Thus, for
	      instance, <literal>&Saction;(upgrade)</literal> matches
	      exactly those packages that you have already decided to
	      upgrade, not packages which <emphasis>could</emphasis>
	      be upgraded in the future (for that, use
	      <literal>&Supgradable;</literal>).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchAllVersions'>
	  <term><literal>?all-versions(<replaceable>pattern</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches any package whose versions all match the given
	      expression.  Each version of a package will be
	      separately tested against
	      <replaceable>pattern</replaceable>, and the package will
	      match if all of its versions match.  Packages without
	      versions, such as virtual packages, will always be
	      matched by this search term.
	    </para>

	    <para>
	      This term may not be used in a context in which the
	      versions to match against have already been narrowed,
	      such as within &Sdepends; or &Snarrow;.  However, it may
	      always be used within &Swiden;.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchAnyVersion'>
	  <term><literal>?any-version(<replaceable>pattern</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches a package if any one of its versions matches the
	      enclosed pattern.  This is the dual to &Sall-versions;.
	    </para>

	    <para>
	      This term may not be used in a context in which the
	      versions to match against have already been narrowed,
	      such as within &Sdepends; or &Snarrow;.  However, it may
	      always be used within &Swiden;.
	    </para>

	    <note>
	      <para>
		This term is closely related to &Snarrow;.
		In fact,
		<literal>?any-version(<replaceable>pattern1</replaceable>
		<replaceable>pattern2</replaceable>)</literal> is exactly
		the same as
		<literal>&Snarrow;(<replaceable>pattern1</replaceable>,
		<replaceable>pattern2</replaceable>)</literal>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchArchitecture'>
	  <term><literal>?architecture(<replaceable>architecture</replaceable>)</literal>, <literal>~r<replaceable>architecture</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches package versions for the given
	      <replaceable>architecture</replaceable>.  For instance,
	      <quote><literal>?architecture(amd64)</literal></quote>
	      matches <literal>amd64</literal> packages, while
	      <quote><literal>?architecture(all)</literal></quote>
	      matches arch-independent packages.  Also accepts the
	      special values <literal>native</literal> and
	      <literal>foreign</literal>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchArchive'>
	  <term><literal>?archive(<replaceable>archive</replaceable>)</literal>, <literal>~A<replaceable>archive</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches package versions which are available from an
	      archive that matches the regular expression
	      <replaceable>archive</replaceable>.  For instance,
	      <quote><literal>?archive(testing)</literal></quote>
	      matches any package available from the
	      <literal>testing</literal> archive.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchAutomatic'>
	  <term><literal>?automatic</literal>, <literal>~M</literal></term>

	  <listitem>
	    <para>
	      Matches packages which were automatically installed.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchBind'>
	  <term>
	    <literal>?bind(<replaceable>variable</replaceable>,
	    <replaceable>pattern</replaceable>)</literal>,
	    <literal>?<replaceable>variable</replaceable>:<replaceable>term-name</replaceable><optional>(<replaceable>args</replaceable>)</optional></literal>
	  </term>

	  <listitem>
	    <para>
	      Matches any package or version if the given
	      <replaceable>pattern</replaceable> matches the package or
	      version bound to <replaceable>variable</replaceable>,
	      which must be defined in an enclosing &Sfor;.
	    </para>

	    <example id='exampleSearchBind'>
	      <title>Use of the <literal>?bind</literal> term</title>

	      <para>
		<literal>&Sfor; x: &Sdepends;(&Sdepends;(&Sfor; z: ?bind(x, &Sdepends;(&Sequal;z))))</literal>
	      </para>

	      <para>
		<literal>&Sfor; x: &Sdepends;(&Sdepends;(&Sfor; z: ?x:<link linkend='searchDep'>depends</link>(&Sequal;z)))</literal>
	      </para>
	    </example>

	    <para>
	      The two search patterns in the above example both match
	      any package <literal>x</literal> such that
	      <literal>x</literal> depends on a package
	      <literal>y</literal> which in turn depends on a package
	      <literal>z</literal> such that <literal>x</literal> also
	      depends directly on <literal>z</literal>.  The first
	      pattern uses <literal>?bind</literal> directly, while
	      the second one uses an equivalent shorthand syntax.
	    </para>

	    <para>
	      See <xref linkend='secExplicitMatchers'/> for more
	      information.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchBroken'>
	  <term><literal>?broken</literal>, <literal>~b</literal></term>

	  <listitem>
	    <para>
	      Matches packages that are <quote>broken</quote>: they have an
	      unfulfilled dependency, predependency, breaks, or conflict.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchBrokenType'>
	  <term><literal>?broken-<replaceable>depType</replaceable></literal>, <literal>~B<replaceable>depType</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which have an unfulfilled (<quote>broken</quote>)
	      dependency of the given <replaceable>depType</replaceable>.
	      <replaceable>depType</replaceable> can be
	      <quote><literal>depends</literal></quote>,
	      <quote><literal>predepends</literal></quote>,
	      <quote><literal>recommends</literal></quote>,
	      <quote><literal>suggests</literal></quote>,
	      <quote><literal>breaks</literal></quote>,
	      <quote><literal>conflicts</literal></quote>, or
	      <quote><literal>replaces</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchBrokenTypeTerm'>
	  <term><literal>?broken-<replaceable>depType</replaceable>(<replaceable>pattern</replaceable>)</literal>, <literal>~DB<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages with an unsatisfied dependency of type
	      <replaceable>depType</replaceable> on a package matching
	      <replaceable>pattern</replaceable>.
	      <replaceable>depType</replaceable> may be any one of the
	      dependency types listed in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>?broken-<replaceable>depType</replaceable></literal></link>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchConflicts'>
	  <term><literal>?conflicts(<replaceable>pattern</replaceable>)</literal>, <literal>~C<replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which conflict with a package matching
	      the given <replaceable>pattern</replaceable>.  For
	      instance,
	      <quote><literal>?conflicts(&Smaintainer;(dburrows@debian.org))</literal></quote>
	      matches any package which conflicts with a package I
	      maintain.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchConfigFiles'>
	  <term><literal>?config-files</literal>, <literal>~c</literal></term>

	  <listitem>
	    <para>
	      Matches packages which have been removed, but whose
	      configuration files remain on the system (ie, they were
	      removed but not purged).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchDep'>
	  <term><literal>?<replaceable>depType</replaceable>(<replaceable>pattern</replaceable>)</literal>, <literal>~D<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      <replaceable>depType</replaceable> may be any one of the
	      dependency types given in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>?broken-<replaceable>depType</replaceable></literal></link>,
	      as well as <literal>provides</literal>: for instance,
	      <literal>&Sdepends;(libpng3)</literal> will match any
	      package that depends on <literal>libpng3</literal>.  If
	      the short form (<literal>~D</literal>) is used and
	      <replaceable>depType</replaceable> is not present, it
	      defaults to <literal>depends</literal>.
	    </para>

	    <para>
	      If <replaceable>depType</replaceable> is
	      <quote><literal>provides</literal></quote>, matches
	      packages that provide a package matching
	      <replaceable>pattern</replaceable> (the equivalent of
	      &Sprovides;).  Otherwise, matches packages which declare
	      a dependency of type <replaceable>depType</replaceable>
	      upon a package version which matches
	      <replaceable>pattern</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchDescription'>
	  <term><literal>?description(<replaceable>description</replaceable>)</literal>, <literal>~d<replaceable>description</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages whose description matches the regular
	      expression <replaceable>description</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchEssential'>
	  <term><literal>?essential</literal>, <literal>~E</literal></term>

	  <listitem>
	    <para>
	      Matches Essential packages.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchExactName'>
	  <term><literal>?exact-name(<replaceable>name</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches packages named <replaceable>name</replaceable>.
	      This is similar to &Sname;, but the name must match
	      exactly.  For instance, the following pattern will match
	      only the package <systemitem>apt</systemitem>; with
	      &Sname;, it would also match
	      <systemitem>aptitude</systemitem>,
	      <systemitem>uvccapture</systemitem>, etc.
	    </para>

	    <example id='idSearchExactName'>
	      <title>Use of the <literal>?exact-name</literal> term</title>
	      <para>
		<literal>?exact-name(apt)</literal>
	      </para>
	    </example>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchFalse'>
	  <term><literal>?false</literal>, <literal>~F</literal></term>

	  <listitem>
	    <para>
	      This term does not match any package.
	      <footnote>
		<para>
		  This is provided largely for symmetry with &Strue;.
		</para>
	      </footnote>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchFor'>
	  <term><literal>?for <replaceable>variable</replaceable>: <replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches <replaceable>pattern</replaceable>, but the given
	      <replaceable>variable</replaceable> may be used inside
	      <replaceable>pattern</replaceable> to refer to the package
	      or package version this term to.
	    </para>

	    <para>
	      You can use <replaceable>variable</replaceable> in two
	      ways.  To apply a <literal>?</literal>-style term to
	      the variable, write
	      <literal>?<replaceable>variable</replaceable>:<replaceable>term-name</replaceable>(<replaceable>args</replaceable>)</literal>;
	      for instance, <literal>?x:<link
	      linkend='searchDep'>depends</link>(apt)</literal>.  In
	      addition, the term
	      <literal>&Sequal;<replaceable>variable</replaceable></literal>
	      will select any package or version that matches the
	      value of the given <replaceable>variable</replaceable>.
	    </para>

	    <para>
	      For instance, the following term will match any package
	      <literal>x</literal> that both depends and recommends a
	      second package <literal>y</literal>.
	    </para>

	    <example id='exampleSearchFor'>
	      <title>Use of the <literal>?for</literal> term</title>
	      <para>
		<literal>
		  ?for x: &Sdepends;( ?for y: ?x:<link linkend='searchDep'>recommends</link>( &Sequal;y ) )
		</literal>
	      </para>
	    </example>

	    <para>
	      See <xref linkend='secExplicitMatchers'/> for more
	      information.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchGarbage'>
	  <term><literal>?garbage</literal>, <literal>~g</literal></term>

	  <listitem>
	    <para>
	      Matches packages which are not installed, or which were
	      automatically installed and are not depended upon by any
	      installed package.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchInstalled'>
	  <term><literal>?installed</literal>, <literal>~i</literal></term>

	  <listitem>
	    <para>
	      Matches package versions which are currently installed.
	    </para>

	    <para>
	      Since all versions are tested by default, this normally
	      matches packages which are currently installed.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchMaintainer'>
	  <term><literal>?maintainer(<replaceable>maintainer</replaceable>)</literal>, <literal>~m<replaceable>maintainer</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages whose Maintainer field matches the
	      regular expression
	      <replaceable>maintainer</replaceable>.  For instance,
	      <quote><literal>&Smaintainer;(joeyh)</literal></quote>
	      will find all packages maintained by Joey Hess.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchMultiArch'>
	  <term><literal>?multiarch(<replaceable>multiarch</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches packages with the multi-arch capability
	      specified by <replaceable>multiarch</replaceable>.  For instance,
	      <quote><literal>&Smultiarch;(foreign)</literal></quote>
	      will find all packages which can satisfy dependencies of
	      packages for another architecture.
	      <quote><literal>&Smultiarch;(none)</literal></quote>
	      will select packages with no multi-arch capability.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchNarrow'>
	  <term>
	    <literal>?narrow(<replaceable>filter</replaceable>, <replaceable>pattern</replaceable>)</literal>, <literal>~S <replaceable>filter</replaceable> <replaceable>pattern</replaceable></literal>
	  </term>

	  <listitem>
	    <para>
	      This term <quote>narrows</quote> the search to package
	      versions matching <replaceable>filter</replaceable>.  In
	      particular, it matches any package version which matches
	      both <replaceable>filter</replaceable> and
	      <replaceable>pattern</replaceable>.  The string value of
	      the match is the string value of
	      <replaceable>pattern</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id="searchTermName">
	  <term><literal>?name(<replaceable>name</replaceable>)</literal>, <literal>~n<replaceable>name</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages whose name matches the regular
	      expression <replaceable>name</replaceable>.  For
	      instance, most of the packages that match
	      <quote><literal>&Sname;(^lib)</literal></quote> are
	      libraries of one sort or another.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchNew'>
	  <term><literal>?new</literal>, <literal>~N</literal></term>

	  <listitem>
	    <para>
	      Matches packages which are <quote>new</quote>: that is,
	      they have been added to the archive since the last time
	      the list of packages was cleared using &actions-forget;
	      or the command-line action <literal><link
	      linkend='cmdlineForgetNew'>forget-new</link></literal>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchObsolete'>
	  <term>
	    <literal>?obsolete</literal>, <literal>~o</literal>
	  </term>

	  <listitem>
	    <para>
	      This term matches any installed package which is not
	      available in any version from any archive.  These
	      packages appear as <quote>Obsolete or Locally
	      Installed</quote> in the visual interface.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchOrigin'>
	  <term><literal>?origin(<replaceable>origin</replaceable>)</literal>, <literal>~O<replaceable>origin</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches package versions whose origin matches the
	      regular expression <replaceable>origin</replaceable>.
	      For instance,
	      <quote><literal>!?origin(debian)</literal></quote> will
	      find any unofficial packages on your system (packages
	      not from the Debian archive).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id="searchProvides">
	  <term><literal>?provides(<replaceable>pattern</replaceable>)</literal>, <literal>~P<replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches package versions which provide a package that
	      matches the <replaceable>pattern</replaceable>.  For
	      instance,
	      <quote><literal>?provides(mail-transport-agent)</literal></quote>
	      will match all the packages that provide
	      <quote><literal>mail-transport-agent</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchPriority'>
	  <term><literal>?priority(<replaceable>priority</replaceable>)</literal>, <literal>~p<replaceable>priority</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages whose priority is
	      <replaceable>priority</replaceable>;
	      <replaceable>priority</replaceable> must be
	      <literal>extra</literal>, <literal>important</literal>,
	      <literal>optional</literal>,
	      <literal>required</literal>, or
	      <literal>standard</literal>.  For instance,
	      <quote><literal>?priority(required)</literal></quote>
	      matches packages whose priority is
	      <quote><literal>required</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchReverseDep'>
	  <term><literal>?reverse-<replaceable>depType</replaceable>(<replaceable>pattern</replaceable>)</literal>, <literal>~R<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      <replaceable>depType</replaceable> may be either
	      <quote><literal>provides</literal></quote> or one of the
	      dependency types given in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>?broken-<replaceable>depType</replaceable></literal></link>.
	      If <replaceable>depType</replaceable> is not present, it
	      defaults to <literal>depends</literal>.
	    </para>

	    <para>
	      If <replaceable>depType</replaceable> is
	      <quote><literal>provides</literal></quote>, matches
	      packages whose name is provided by a package version
	      matching <replaceable>pattern</replaceable>.  Otherwise,
	      matches packages which a package version matching
	      <replaceable>pattern</replaceable> declares a dependency of
	      type <replaceable>depType</replaceable> upon.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchReverseBrokenDep'>
	  <term><literal>?reverse-broken-<replaceable>depType</replaceable>(<replaceable>pattern</replaceable>)</literal>, <literal>?broken-reverse-<replaceable>depType</replaceable>(<replaceable>pattern</replaceable>)</literal>, <literal>~RB<optional><replaceable>depType</replaceable>:</optional><replaceable>pattern</replaceable></literal></term>

	  <listitem>
	    <para>
	      <replaceable>depType</replaceable> may be either
	      <quote><literal>provides</literal></quote> or one of the
	      dependency types given in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>?broken-<replaceable>depType</replaceable></literal></link>.
	      If <replaceable>depType</replaceable> is not present, it
	      defaults to <literal>depends</literal>.
	    </para>

	    <para>
	      Matches packages which a package version matching
	      <replaceable>pattern</replaceable> declares an unsatisfied
	      dependency of type <replaceable>depType</replaceable> upon.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchSection'>
	  <term>
	    <literal>?section(<replaceable>section</replaceable>)</literal>, <literal>~s<replaceable>section</replaceable></literal>
	  </term>

	  <listitem>
	    <para>
	      Matches packages whose section matches the regular
	      expression <replaceable>section</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchSourcePackage'>
	  <term>
	    <literal>?source-package(<replaceable>name</replaceable>)</literal>
	  </term>

	  <listitem>
	    <para>
	      Matches packages whose source package name matches the
	      regular expression <replaceable>name</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchSourceVersion'>
	  <term>
	    <literal>?source-version(<replaceable>version</replaceable>)</literal>
	  </term>

	  <listitem>
	    <para>
	      Matches packages whose source version matches the
	      regular expression <replaceable>version</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTag'>
	  <term><literal>?tag(<replaceable>tag</replaceable>)</literal>, <literal>~G<replaceable>tag</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages whose Tag field matches the regular
	      expression <replaceable>tag</replaceable>.  For
	      instance, the pattern
	      <literal>?tag(game::strategy)</literal> would match
	      strategy games.
	    </para>

	    <para>
	      For more information on tags and debtags, see <ulink
	      url='http://debtags.alioth.debian.org'/>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTask'>
	  <term>
	    <literal>?task(<replaceable>task</replaceable>)</literal>, <literal>~t<replaceable>task</replaceable></literal>
	  </term>

	  <listitem>
	    <para>
	      Matches packages that appear in a task whose name
	      matches the regular expression
	      <replaceable>task</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTerm'>
	  <term>
	    <literal>?term(<replaceable>keyword</replaceable>)</literal>
	  </term>

	  <listitem>
	    <para>
	      This term performs a full-text search for
	      <replaceable>keyword</replaceable> in the apt package
	      cache.  When used with <quote><literal>aptitude
	      search</literal></quote>, <link
	      linkend='menuSearchLimit'>&search-limit;</link> in the
	      curses front-end, or typed into a package search box in
	      the GTK+ front-end, this term will allow &aptitude; to
	      accelerate the search using a Xapian index.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTermPrefix'>
	  <term>
	    <literal>?term-prefix(<replaceable>keyword</replaceable>)</literal>
	  </term>

	  <listitem>
	    <para>
	      This term performs a full-text search for any keyword
	      beginning with <replaceable>keyword</replaceable> in the
	      apt package cache.  When used with
	      <quote><literal>aptitude search</literal></quote>, <link
	      linkend='menuSearchLimit'>&search-limit;</link> in the
	      curses front-end, or typed into a package search box in
	      the GTK+ front-end, this term will allow &aptitude; to
	      accelerate the search using a Xapian index.
	    </para>

	    <para>
	      This is similar to &Sterm;, but matches extensions of
	      the <replaceable>keyword</replaceable>.  For instance,
	      the following search pattern will match any package
	      indexed under the keywords <literal>hour</literal>,
	      <literal>hourglass</literal>, <literal>hourly</literal>,
	      and so on:
	    </para>

	    <example id='exampleTermPrefix'>
	      <title>Use of the <literal>?term-prefix</literal> term</title>
	      <para>
		<literal>
		  ?term-prefix(hour)
		</literal>
	      </para>
	    </example>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTrue'>
	  <term>
	    <literal>?true</literal>, <literal>~T</literal>
	  </term>

	  <listitem>
	    <para>
	      This term matches any package.  For instance,
	      <quote><literal>&Sinstalled;&Sprovides;(&Strue;)</literal></quote>
	      matches installed packages which are provided by any
	      package.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchUpgradable'>
	  <term>
	    <literal>?upgradable</literal>, <literal>~U</literal>
	  </term>

	  <listitem>
	    <para>
	      This term matches any installed package which can be
	      upgraded.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchUserTag'>
	  <term>
	    <literal>?user-tag(<replaceable>tag</replaceable>)</literal>
	  </term>

	  <listitem>
	    <para>
	      This term matches any package that is marked with a
	      user-tag matching the regular expression
	      <replaceable>tag</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id="searchTermVersion">
	  <term>
	    <literal>?version(<replaceable>version</replaceable>)</literal>, <literal>~V<replaceable>version</replaceable></literal>
	  </term>

	  <listitem>
	    <para>
	      Matches any package version whose version number matches
	      the regular expression
	      <replaceable>version</replaceable>, with the exceptions
	      noted below.  For instance,
	      <quote><literal>?version(debian)</literal></quote>
	      matches packages whose version contains
	      <quote><literal>debian</literal></quote>.
	    </para>

	    <para>
	      The following values of
	      <replaceable>version</replaceable> are treated
	      specially.  To search for version numbers containing
	      these values, preface the value with a backslash; for
	      instance, to find packages whose version number contains
	      <literal>CURRENT</literal>, search for
	      <literal>\CURRENT</literal>.

	      <itemizedlist>
		<listitem>
		  <para>
		    <literal>CURRENT</literal> matches the currently
		    installed version of a package, if any.
		  </para>
		</listitem>

		<listitem>
		  <para>
		    <literal>CANDIDATE</literal> matches the version,
		    if any, of the package that will be installed if
		    you press <keycap>+</keycap> on the package or run
		    <literal>aptitude install</literal> on it.
		  </para>
		</listitem>

		<listitem>
		  <para>
		    <literal>TARGET</literal> matches the version of a
		    package that is currently targeted for
		    installation, if any.
		  </para>
		</listitem>
	      </itemizedlist>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchVirtual'>
	  <term>
	    <literal>?virtual</literal>, <literal>~v</literal>
	  </term>

	  <listitem>
	    <para>
	      Matches any package which is purely virtual: that is,
	      its name is provided by a package or mentioned in a
	      dependency, but no package of that name exists.  For
	      instance,
	      <quote><literal>?virtual!&Sprovides;(&Strue;)</literal></quote>
	      matches packages which are virtual and are not provided
	      by any package: ie, packages which are depended upon but
	      do not exist.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchWiden'>
	  <term>
	    <literal>?widen(<replaceable>pattern</replaceable>)</literal>, <literal>~W<replaceable>pattern</replaceable></literal> 
	  </term>

	  <listitem>
	    <para>
	      <quote>Widens</quote> the match: if the versions to
	      match against have been limited by an enclosing term
	      (such as &Sdepends;), these limits are dropped.  Thus,
	      <literal>&Swiden;(<replaceable>pattern</replaceable>)</literal>
	      matches a package version if
	      <replaceable>pattern</replaceable> matches
	      <emphasis>any</emphasis> version of that package.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      </section>
    </section>

    <section id='secConfig'>
      <title>Customizing &aptitude;</title>

      <section>
	<title>Customizing the package list</title>

	<para>
	  The package list can be heavily customized: how packages are
	  displayed, how the package hierarchy is formed, how packages
	  are sorted, and even how the display is organized are all
	  open to change.
	</para>

	<section id='secDisplayFormat'>
	  <title>Customizing how packages are displayed</title>

	  <para>
	    This section describes how to configure the contents and
	    format of the package list, status line, and header line,
	    as well as the output of <literal><link
	    linkend='cmdlineSearch'>aptitude search</link></literal>.
	  </para>

	  <para>
	    The format of each of these locations is defined by a
	    <quote>format string</quote>.  A format string is a string of text
	    containing <literal>%</literal>-escapes such as
	    <literal>%p</literal>, <literal>%S</literal>, and so on.
	    The resulting output is created by taking the text and
	    replacing the <literal>%</literal>-escapes according to
	    their meanings (given below).
	  </para>

	  <para>
	    A <literal>%</literal>-escape can either have a fixed
	    size, in which case it is always replaced by the same
	    amount of text (with extra space characters added to fill
	    it out as necessary), or it can be <quote>expandable</quote>, meaning
	    that it takes up the space that is not claimed by
	    fixed-size columns.  If there are several expandable
	    columns, the extra space is divided evenly between them.
	  </para>

	  <para>
	    All <literal>%</literal>-escapes come with a default size
	    and/or expandability.  The size of a
	    <literal>%</literal>-escape can be changed by writing it
	    between the <literal>%</literal> and the character
	    identifying the escape; for instance,
	    <literal>%20V</literal> generates the <link
	    linkend='formatCandVer'>candidate version</link> of the
	    package, 20 characters wide.  Placing a question mark
	    (<literal>?</literal>) between the <literal>%</literal>
	    and the character identifying the escape causes the
	    column's <quote>basic</quote> width to vary depending on
	    its content.  Note that the resulting columns might not
	    line up vertically!
	  </para>

	  <para>
	    If you want a particular <literal>%</literal>-escape to be
	    expandable, even though it normally has a fixed width,
	    place a pound sign (ie,
	    <quote><literal>#</literal></quote>) immediately after it.
	    For instance, to display the candidate version of a
	    package, no matter how long it is, use the format string
	    <literal>%V#</literal>.  You can also place
	    <literal>#</literal> after something that is not a
	    <literal>%</literal>-escape; &aptitude; will
	    <quote>expand</quote> the text preceding the
	    <literal>#</literal> by inserting extra spaces after it.
	  </para>

	  <para>
	    In summary, the syntax of a <literal>%</literal>-escape is:
	  </para>

	  <synopsis><literal>%</literal><optional><replaceable>width</replaceable></optional><optional><literal>?</literal></optional><replaceable>code</replaceable><optional><literal>#</literal></optional></synopsis>

	  <para>
	    The configuration variables <literal><link
	    linkend='configPackage-Display-Format'>Aptitude::UI::Package-Display-Format</link></literal>,
	    <literal><link
	    linkend='configPackage-Status-Format'>Aptitude::UI::Package-Status-Format</link></literal>,
	    and <literal><link
	    linkend='configPackage-Header-Format'>Aptitude::UI::Package-Header-Format</link></literal>
	    define the default formats the package list, the header at
	    the top of the package list, and the status line below the
	    package list respectively.  To change how the results of
	    an <literal><link linkend='cmdlineSearch'>aptitude
	    search</link></literal> command are displayed, use the
	    <literal><link
	    linkend='cmdlineOptionFormat'>-F</link></literal> option.
	  </para>

	  <para>
	    The following <literal>%</literal>-escapes are available
	    in format strings:
	  </para>

	  <note>
	    <para>
	      Some of the descriptions below refer to <quote>the package</quote>.
	      In the GUI, this is either the package being displayed
	      or the currently selected package; in the command-line
	      search, this is the package being displayed.
	    </para>
	  </note>

	  <segmentedlist>
	    <segtitle>Escape</segtitle>
	    <segtitle>Name</segtitle>
	    <segtitle>Default size</segtitle>
	    <segtitle>Expandable</segtitle>
	    <segtitle>Description</segtitle>

	    <seglistitem>
	      <seg><literal>%%</literal></seg>
	      <seg>Literal <literal>%</literal></seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		This is not really an escape; it simply inserts a
		percent sign into the output at the point at which it
		occurs.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%#<replaceable>number</replaceable></literal></seg>
	      <seg>Parameter Replacement</seg>
	      <seg>Variable</seg>
	      <seg>No</seg>
	      <seg>
		In some circumstances, a display format string will
		have <quote>parameters</quote>: for instance, in the
		command-line <literal>search</literal>, the groups
		matched by the search are used as parameters when
		displaying the result.  This format code will be
		replaced by the parameter indicated by
		<replaceable>number</replaceable>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%a</literal></seg>
	      <seg>Action Flag</seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		A single-character flag summarizing any action to be
		performed on the package, as described in
		<xref linkend='figureActionFlag'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%A</literal></seg>
	      <seg>Action</seg>
	      <seg>10</seg>
	      <seg>No</seg>
	      <seg>
		A somewhat more verbose description of the action to
		be performed on the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%B</literal></seg>
	      <seg>Broken Count</seg>
	      <seg>12</seg>
	      <seg>No</seg>
	      <seg>
		If there are no broken packages, produces nothing.
		Otherwise, produces a string such as
		<quote><computeroutput>Broken: 10</computeroutput></quote>
		describing the number of broken packages.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%c</literal></seg>
	      <seg>Current State Flag</seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		A single-character flag summarizing the current state
		of the package, as described in <xref
		linkend='figureCurrentFlag'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%C</literal></seg>
	      <seg>Current State</seg>
	      <seg>11</seg>
	      <seg>No</seg>
	      <seg>
		A more verbose description of the current state of the
		package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%d</literal></seg>
	      <seg>Description</seg>
	      <seg>40</seg>
	      <seg>Yes</seg>
	      <seg>
		The package's short description.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%D</literal></seg>
	      <seg>Package Size</seg>
	      <seg>8</seg>
	      <seg>No</seg>
	      <seg>
		The size of the package file containing the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%H</literal></seg>
	      <seg>Hostname</seg>
	      <seg>15</seg>
	      <seg>No</seg>
	      <seg>
		The name of the computer on which &aptitude; is running.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%i</literal></seg>
	      <seg>Pin priority</seg>
	      <seg>4</seg>
	      <seg>No</seg>
	      <seg>
		Displays the highest priority assigned to a package
		version; for packages, displays the priority of the
		version which will be forced to be installed (if any).
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%I</literal></seg>
	      <seg>Installed Size</seg>
	      <seg>8</seg>
	      <seg>No</seg>
	      <seg>
		The (estimated) amount of space the package takes up on disk.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%m</literal></seg>
	      <seg>Maintainer</seg>
	      <seg>30</seg>
	      <seg>Yes</seg>
	      <seg>
		The maintainer of the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%M</literal></seg>
	      <seg>Automatic Flag</seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		If the package is automatically installed, outputs
		<quote><computeroutput>A</computeroutput></quote>; otherwise,
		outputs nothing.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%n</literal></seg>
	      <seg>Program Version</seg>
	      <seg>The length of <quote>&VERSION;</quote>.</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the version of &aptitude; that is running,
		currently
		<quote><computeroutput>&VERSION;</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%N</literal></seg>
	      <seg>Program Name</seg>
	      <seg>The length of the name.</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the name of the program; usually
		<quote><computeroutput>aptitude</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%o</literal></seg>
	      <seg>Download Size</seg>
	      <seg>17</seg>
	      <seg>No</seg>
	      <seg>
		If no packages are going to be installed, outputs
		nothing.  Otherwise, outputs a string describing the
		total size of all the package files which will be
		installed (an estimate of how much needs to be
		downloaded); for instance, <quote><computeroutput>DL size:
		1000B</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%p</literal></seg>
	      <seg>Package Name</seg>
	      <seg>30</seg>
	      <seg>Yes</seg>
	      <seg>
		Outputs the name of the package.  When a package is
		displayed in a tree context, the name of the package
		will be indented, if possible, according to its depth
		in the tree.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%P</literal></seg>
	      <seg>Priority</seg>
	      <seg>9</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the priority of the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%r</literal></seg>
	      <seg>Reverse Depends Count</seg>
	      <seg>2</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the approximate number of installed packages
		which depend upon the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%R</literal></seg>
	      <seg>Abbreviated Priority</seg>
	      <seg>3</seg>
	      <seg>No</seg>
	      <seg>
		Outputs an abbreviated description of the package's
		priority: for instance,
		<quote><computeroutput>Important</computeroutput></quote> becomes
		<quote><computeroutput>Imp</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%s</literal></seg>
	      <seg>Section</seg>
	      <seg>10</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the section of the package.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%S</literal></seg>
	      <seg>Trust Status</seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		If the package is untrusted, displays the letter "U".
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%t</literal></seg>
	      <seg>Archive</seg>
	      <seg>10</seg>
	      <seg>Yes</seg>
	      <seg>
		The archive in which the package is found.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%T</literal></seg>
	      <seg>Tagged</seg>
	      <seg>1</seg>
	      <seg>No</seg>
	      <seg>
		Outputs <quote><computeroutput>*</computeroutput></quote> if the
		package is tagged, nothing
		otherwise.<footnote><para>Currently tagging is not
		supported; this escape is for future
		use.</para></footnote>
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%u</literal></seg>
	      <seg>Disk Usage Change</seg>
	      <seg>30</seg>
	      <seg>No</seg>
	      <seg>
		If the scheduled actions will alter the amount of
		space used on the disk, outputs a description of the
		change in disk space; for instance,
		<quote><computeroutput>Will use 100MB of disk
		space.</computeroutput></quote>
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%v</literal></seg>
	      <seg>Current Version</seg>
	      <seg>14</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the currently installed version of the
		package, or
		<computeroutput>&lt;none&gt;</computeroutput> if the
		package is not currently installed.
	      </seg>
	    </seglistitem>

	    <seglistitem id='formatCandVer'>
	      <seg><literal>%V</literal></seg>
	      <seg>Candidate Version</seg>
	      <seg>14</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the version of the package which would be
		installed if &package-install; were issued on the
		package, or
		<computeroutput>&lt;none&gt;</computeroutput> if the
		package is not currently available.
	      </seg>
	    </seglistitem>

	    <seglistitem id='formatSizeChange'>
	      <seg><literal>%Z</literal></seg>
	      <seg>Size Change</seg>
	      <seg>9</seg>
	      <seg>No</seg>
	      <seg>
		Outputs how much additional space will be used or how
		much space will be freed by installing, upgrading, or
		removing a package.
	      </seg>
	    </seglistitem>
	  </segmentedlist>
	</section>

	<section id='secGroupingPolicy'>
	  <title>Customizing the package hierarchy</title>

	  <para>
	    The package hierarchy is generated by a
	    <firstterm>grouping policy</firstterm>: rules describing
	    how the hierarchy should be built.  The grouping policy
	    describes a <quote>pipeline</quote> of rules; each rule
	    can discard packages, create sub-hierarchies in which
	    packages reside, or otherwise manipulate the tree.  The
	    configuration items <literal><link
	    linkend='configDefault-Grouping'>Aptitude::UI::Default-Grouping</link></literal>
	    and <literal><link
	    linkend='configDefault-Preview-Grouping'>Aptitude::UI::Default-Preview-Grouping</link></literal>
	    set the grouping policies for newly created package lists
	    and preview screens, respectively.  You can set the
	    grouping policy for the <emphasis>current</emphasis>
	    package list by pressing <keycap>G</keycap>.
	  </para>

	  <para>
	    The grouping policy is described by a comma-separated list
	    of rules:
	    <literal><replaceable>rule1</replaceable>,<replaceable>rule2</replaceable>,<replaceable>...</replaceable></literal>.
	    Each <replaceable>rule</replaceable> consists of the name
	    of the rule, possibly followed by arguments: for instance,
	    <literal>versions</literal> or
	    <literal>section(subdir)</literal>.  Whether arguments are
	    required and how many arguments are required (or allowed)
	    depends on the type of rule.
	  </para>

	  <para>
	    Rules can be <firstterm>non-terminal</firstterm> or
	    <firstterm>terminal</firstterm>.  A non-terminal rule will
	    process a package by generating some part of the
	    hierarchy, then passing the package on to a later rule.  A
	    terminal rule, on the other hand, will also generate part
	    of the tree (typically items corresponding to the
	    package), but does not pass its package to a later rule.
	    If no terminal rule is specified, &aptitude; will use the
	    default rule, which is to create the standard <quote>package
	    items</quote>.
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term><synopsis>action</synopsis></term>

	      <listitem>
		<para>
		  Groups packages according to the action scheduled on
		  them; packages that are not upgradable and will be
		  unchanged are ignored.  This is the grouping that is
		  used in preview trees.
		</para>
	      </listitem>
	    </varlistentry>

            <varlistentry>
              <term><synopsis>architecture</synopsis></term>

              <listitem>
                <para>
                  Groups packages according to their architecture.
                </para>
              </listitem>
            </varlistentry>

	    <varlistentry>
	      <term><synopsis>deps</synopsis></term>

	      <listitem>
		<para>
		  This is a terminal rule.
		</para>

		<para>
		  Creates standard package items which can be expanded
		  to reveal the dependencies of the package.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>filter(<replaceable>pattern</replaceable>)</synopsis></term>

	      <listitem>
		<para>
		  Include only packages for which at least one version
		  matches <replaceable>pattern</replaceable>.
		</para>

		<para>
		  If <replaceable>pattern</replaceable> is
		  <quote>missing</quote>, no packages are discarded.
		  This is a backwards compatibility feature and may be
		  removed in the future.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>firstchar</synopsis></term>

	      <listitem>
		<para>
		  Groups packages based on the first character of
		  their name.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>hier</synopsis></term>

	      <listitem>
		<para>
		  Groups packages according to an extra data file
		  describing a <quote>hierarchy</quote> of packages.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>pattern(<replaceable>pattern</replaceable> <optional>=> <replaceable>title</replaceable></optional> <optional>{ <replaceable>policy</replaceable> }</optional> <optional>, ...</optional>)</synopsis></term>

	      <listitem>
		<para>
		  A customizable grouping policy.  Each version of
		  every package is matched against the given
		  <replaceable>pattern</replaceable>s.  The first
		  match found is used to assign a
		  <replaceable>title</replaceable> to the package;
		  packages are then grouped by their
		  <replaceable>title</replaceable>.  Strings of the
		  form <literal>\N</literal> that occur in
		  <replaceable>title</replaceable> will be replaced by
		  the Nth result of the match.  If
		  <replaceable>title</replaceable> is not present, it
		  is assumed to be <literal>\1</literal>.  Note that
		  packages which do not match any
		  <replaceable>pattern</replaceable>s will not appear
		  in the tree at all.
		</para>

		<example>
		  <title>Use of <literal>pattern</literal> to group packages by their maintainer</title>

		  <para>
		    <literal>pattern(&Smaintainer;() => \1)</literal>
		  </para>
		</example>

		<para>
		  The example above will group packages according to
		  their Maintainer field.  The policy
		  <literal>pattern(&Smaintainer;())</literal> will do
		  the same thing, as the absent
		  <replaceable>title</replaceable> defaults to
		  <literal>\1</literal>.
		</para>

		<para>
		  Instead of <literal>=>
		  <replaceable>title</replaceable></literal>, an entry
		  may end with <literal>||</literal>.  This indicates
		  that packages matching the corresponding
		  <replaceable>pattern</replaceable> will be inserted
		  into the tree at the same level as the
		  <literal>pattern</literal> grouping, rather than
		  being placed in subtrees.
		</para>

		<example>
		  <title>
		    Use of <literal>pattern</literal> with some
		    packages placed at the top level
		  </title>

		  <para>
		    <literal>pattern(&Saction;(remove) => Packages
		    Being Removed, &Strue; ||)</literal>
		  </para>
		</example>

		<para>
		  The example above will place packages that are being
		  removed into a subtree, and place all the other
		  packages at the current level, grouped according to
		  the policies that follow <literal>pattern</literal>.
		</para>

		<para>
		  By default, all the packages that match each pattern
		  are grouped according to the rules that follow the
		  <literal>pattern</literal> policy.  To specify a
		  different policy for some packages, write the policy
		  in braces (<literal>{}</literal>) after the title of
		  the group, after the <literal>||</literal>, or after
		  the pattern if neither is present.  For instance:
		</para>

		<example id='examplePatternGroupingPolicyWithSubPolicies'>
		  <title>
		    Use of the <literal>pattern</literal> grouping policy with sub-policies
		  </title>

		  <para>
		    <literal>pattern(&Saction;(remove) => Packages
		    Being Removed {}, &Saction;(install) => Packages
		    Being Installed, &Strue; || {status})</literal>
		  </para>
		</example>

		<para>
		  The policy in the above example has the following
		  effects:
		</para>

		<itemizedlist>
		  <listitem>
		    <para>
		      Packages that are being removed are placed into
		      a subtree labeled <quote>Packages Being
		      Removed</quote>; the grouping policy for this
		      subtree is empty, so the packages are placed
		      into a flat list.
		    </para>
		  </listitem>

		  <listitem>
		    <para>
		      Packages that are being installed are placed
		      into a subtree labeled <literal>Packages Being
		      Installed</literal> and grouped according to the
		      policies that follow <literal>pattern</literal>.
		    </para>
		  </listitem>

		  <listitem>
		    <para>
		      All remaining packages are placed at the top
		      level of the tree, grouped according to their
		      status.
		    </para>
		  </listitem>
		</itemizedlist>

		<para>
		  See <xref linkend='secSearchPatterns'/>
		  for more information on the format of
		  <replaceable>pattern</replaceable>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>priority</synopsis></term>

	      <listitem>
		<para>
		  Groups packages according to their priority.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>section<optional>(<replaceable>mode</replaceable><optional>,passthrough</optional>)</optional></synopsis></term>

	      <listitem>
		<para>
		  Groups packages according to their Section field.
		</para>

		<para>
		  <replaceable>mode</replaceable> can be one of the
		  following:
		</para>

		<variablelist>
		  <varlistentry>
		    <term><literal>none</literal></term>

		    <listitem>
		      <para>
			Group based on the whole Section field, so
			categories like <quote>non-free/games</quote> will be
			created.  This is the default if no
			<replaceable>mode</replaceable> is specified.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><literal>topdir</literal></term>

		    <listitem>
		      <para>
			Group based on the part of the Section field
			before the first <literal>/</literal>
			character; if this part of the Section is not
			recognized, or if there is no
			<literal>/</literal>, the first entry in the
			list <literal><link
			linkend='configTop-Sections'>Aptitude::Sections::Top-Sections</link></literal>
			will be used instead.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><literal>subdir</literal></term>

		    <listitem>
		      <para>
			Group based on the part of the Section field
			after the first <literal>/</literal>
			character, if it is contained in the list
			<literal><link
			linkend='configTop-Sections'>Aptitude::Sections::Top-Sections</link></literal>.
			If not, or if there is no
			<literal>/</literal>, group based on the
			entire Section field instead.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><literal>subdirs</literal></term>

		    <listitem>
		      <para>
			Group based on the part of the Section field
			after the first <literal>/</literal>
			character, if the portion of the field
			preceding it is contained in the list
			<literal><link
			linkend='configTop-Sections'>Aptitude::Sections::Top-Sections</link></literal>;
			if not, or if there is no
			<literal>/</literal>, the entire field will be
			used.  If there are multiple
			<literal>/</literal> characters in the portion
			of the field that is used, a hierarchy of
			groups will be formed.  For instance, if
			<quote><literal>games</literal></quote> is not
			a member of <literal><link
			linkend='configTop-Sections'>Aptitude::Sections::Top-Sections</link></literal>,
			then a package with a section of
			<quote><literal>games/arcade</literal></quote>
			will be placed under the top-level heading
			<quote><literal>games</literal></quote>, in a
			sub-tree named
			<quote><literal>arcade</literal></quote>.
		      </para>
		    </listitem>
		  </varlistentry>
		</variablelist>

		<para>
		  If <literal>passthrough</literal> is present,
		  packages which for some reason lack a true Section
		  (for instance, virtual packages) will be passed
		  directly to the next level of grouping without first
		  being placed in sub-categories.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>status</synopsis></term>

	      <listitem>
		<para>
		  Groups packages into the following categories:
		</para>

		<itemizedlist>
		  <listitem><para>Security Updates</para></listitem>
		  <listitem><para>Upgradable</para></listitem>
		  <listitem><para>New</para></listitem>
		  <listitem><para>Installed</para></listitem>
		  <listitem><para>Not Installed</para></listitem>
		  <listitem><para>Obsolete and Locally Created</para></listitem>
		  <listitem><para>Virtual</para></listitem>
		</itemizedlist>
	      </listitem>
	    </varlistentry>

            <varlistentry>
              <term><synopsis>source</synopsis></term>

              <listitem>
                <para>
                  Groups packages according to their source package name.
                </para>
              </listitem>
            </varlistentry>

	    <varlistentry>
	      <term><synopsis>tag<optional>(<replaceable>facet</replaceable>)</optional></synopsis></term>

	      <listitem>
		<para>
		  Groups packages according to the Tag information
		  stored in the Debian package files.  If
		  <replaceable>facet</replaceable> is provided, then
		  only tags corresponding to that facet will be
		  displayed, and packages lacking this facet will be
		  hidden; otherwise, all packages will be displayed at
		  least once (with tagless packages listed separately
		  from packages that have tags).
		</para>

		<para>
		  For more information on debtags, see <ulink
		  url='http://debtags.alioth.debian.org'/>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>task</synopsis></term>

	      <listitem>
		<para>
		  Creates a tree called <quote>Tasks</quote> which contains the
		  available tasks (information on tasks is read from
		  <filename>debian-tasks.desc</filename> in the
		  package <systemitem>tasksel</systemitem>).  The rule
		  following <literal>task</literal> will create its
		  categories as siblings of Tasks.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><synopsis>versions</synopsis></term>

	      <listitem>
		<para>
		  This is a terminal rule.
		</para>

		<para>
		  Creates standard package items which can be expanded
		  to reveal the versions of the package.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</section>

	<section id='secSortingPolicy'>
	  <title>Customizing how packages are sorted</title>

	  <para>
	    By default, packages in the package list or in the output
	    of <literal><link linkend='cmdlineSearch'>aptitude
	    search</link></literal> are sorted by name.  However, it
	    is often useful to sort them according to different
	    criteria (for instance, package size), and &aptitude;
	    allows you to do just that by modifying the
	    <firstterm>sorting policy</firstterm>.
	  </para>

	  <para>
	    Like the grouping policy described in <link
	    linkend='secGroupingPolicy'>the previous section</link>,
	    the sorting policy is a comma-separated list.  Each item
	    in the list is the name of a sorting rule; if packages are
	    <quote>equal</quote> according to the first rule, the second rule is
	    used to sort them, and so on.  Placing a tilde character
	    (<literal>~</literal>) in front of a rule reverses the
	    usual meaning of that rule.  For instance,
	    <literal>priority,~name</literal> will sort packages by
	    priority, but packages with the same priority will be
	    placed in reverse order according to name.
	  </para>

	  <para>
	    To change the sorting policy for an active package list,
	    press <keycap>S</keycap>.  To change the default sorting
	    for all package lists, set the configuration option
	    <literal><link
	    linkend='configDefault-Sorting'>Aptitude::UI::Default-Sorting</link></literal>.
	    To change the sorting policy for <literal><link
	    linkend='cmdlineSearch'>aptitude search</link></literal>,
	    use the <literal><link
	    linkend='cmdlineOptionSort'>--sort</link></literal>
	    command-line option.
	  </para>

	  <para>
	    The available rules are:
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term><literal>installsize</literal></term>

	      <listitem>
		<para>
		  Sorts packages by the estimated amount of size they
		  require when installed.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>name</literal></term>

	      <listitem>
		<para>
		  Sorts packages by name.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>priority</literal></term>

	      <listitem>
		<para>
		  Sorts packages by priority.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>version</literal></term>

	      <listitem>
		<para>
		  Sorts packages according to their version number.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</section>
      </section>

      <section id='secKeybindings'>
	<title>Customizing keybindings</title>

	<para>
	  The keys used to activate commands in &aptitude; can be
	  customized in the <link
	  linkend='secConfigFile'>configuration file</link>.  Every
	  command has an associated configuration variable under
	  <literal>Aptitude::UI::Keybindings</literal>; to change the
	  keystroke bound to a command, just set the corresponding
	  variable to the keystroke.  For instance, to make the key
	  <keycap>s</keycap> perform a search, set
	  <literal>Aptitude::UI::Keybindings::Search</literal> to
	  <quote><literal>s</literal></quote>.  You can require the Control key to
	  be pressed by placing <quote><literal>C-</literal></quote> in front of
	  the key: for instance, using <quote><literal>C-s</literal></quote>
	  instead of <quote><literal>s</literal></quote> would bind Search to
	  <keycombo
	  action='simul'><keycap>Control</keycap><keycap>s</keycap></keycombo>
	  instead of <keycap>s</keycap>.  Finally, you can bind a
	  command to several keys at once using a comma-separated
	  list: for instance, using <quote><literal>s,C-s</literal></quote> would
	  cause both <keycap>s</keycap> and <keycombo
	  action='simul'><keycap>Control</keycap><keycap>s</keycap></keycombo>
	  to perform a search.
	</para>

	<para>
	  The following commands can be bound to keys by setting the
	  variable
	  <literal>Aptitude::UI::Keybindings::<replaceable>command</replaceable></literal>,
	  where <replaceable>command</replaceable> is the name of the
	  command to be bound:
	</para>

	<informaltable>
	  <tgroup cols='3'>
	    <thead>
	      <row>
		<entry>Command</entry>
		<entry>Default</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal>ApplySolution</literal></entry>

		<entry><literal>!</literal></entry>

		<entry>
		  If packages are broken and &aptitude; has suggested
		  a solution to the problem, immediately apply the
		  solution.
		</entry>
	      </row>

	      <row>
		<entry><literal>Begin</literal></entry>
		<entry><literal>home,C-a</literal></entry>
		<entry>
		  Move to the beginning of the current display: to the
		  top of a list, or to the left of a text entry field.
		</entry>
	      </row>

	      <row>
		<entry><literal>BugReport</literal></entry>
		<entry><literal>B</literal></entry>
		<entry>
		  Reports a bug in the currently selected package,
		  using <command>reportbug</command>.
		</entry>
	      </row>

	      <row>
		<entry><literal>Cancel</literal></entry>
		<entry><literal>C-g,escape,C-[</literal></entry>
		<entry>
		  Cancels the current interaction: for instance,
		  discards a dialog box or deactivates the menu.
		</entry>
	      </row>

	      <row>
		<entry><literal>Changelog</literal></entry>
		<entry><literal>C</literal></entry>
		<entry>
		  Displays the <filename>changelog.Debian</filename>
		  of the currently selected package or package
		  version.
		</entry>
	      </row>

	      <row>
		<entry><literal>ChangePkgTreeGrouping</literal></entry>
		<entry><literal>G</literal></entry>
		<entry>
		  Changes the <link
		  linkend='secGroupingPolicy'>grouping policy</link>
		  of the currently active package list.
		</entry>
	      </row>

	      <row>
		<entry><literal>ChangePkgTreeLimit</literal></entry>
		<entry><literal>l</literal></entry>
		<entry>
		  Changes the <link
		  linkend='secSearchPatterns'>limit</link> of the
		  currently active package list.
		</entry>
	      </row>

	      <row>
		<entry><literal>ChangePkgTreeSorting</literal></entry>
		<entry><literal>S</literal></entry>
		<entry>
		  Changes the <link linkend='secSortingPolicy'>sorting
		  policy</link> of the currently active package list.
		</entry>
	      </row>

	      <row>
		<entry><literal>ClearAuto</literal></entry>
		<entry><literal>m</literal></entry>
		<entry>
		  Marks the currently selected package as having been
		  manually installed.
		</entry>
	      </row>

	      <row>
		<entry><literal>CollapseAll</literal></entry>
		<entry><literal>]</literal></entry>
		<entry>
		  Collapses the selected tree and all its children in
		  a hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>CollapseTree</literal></entry>
		<entry>No binding</entry>
		<entry>
		  Collapses the selected tree in a hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>Commit</literal></entry>
		<entry><literal>N</literal></entry>
		<entry>
		  In the <!-- TODO: <link linkend='secHier'>
		  -->hierarchy editor, stores the hierarchy location
		  of the current package and proceeds to the next
		  package.
		</entry>
	      </row>

	      <row>
		<entry><literal>Confirm</literal></entry>
		<entry><literal>enter</literal></entry>
		<entry>
		  In dialog boxes, this is equivalent to pressing
		  <quote><guilabel>Ok</guilabel></quote>; when
		  interacting with a status-line multiple choice
		  question, it chooses the default option.
		</entry>
	      </row>

	      <row>
		<entry><literal>Cycle</literal></entry>
		<entry><literal>tab</literal></entry>
		<entry>
		  Switches the keyboard focus to the next <quote>widget</quote>.
		</entry>
	      </row>

	      <row>
		<entry><literal>CycleNext</literal></entry>
		<entry><literal>f6</literal></entry>
		<entry>
		  Switches to the next active view.
		</entry>
	      </row>

	      <row>
		<entry><literal>CycleOrder</literal></entry>
		<entry><literal>o</literal></entry>
		<entry>
		  Cycles through predefined arrangements of the display.
		</entry>
	      </row>

	      <row>
		<entry><literal>CyclePrev</literal></entry>
		<entry><literal>f7</literal></entry>
		<entry>
		  Switches to the previous active view.
		</entry>
	      </row>

	      <row>
		<entry><literal>DelBOL</literal></entry>
		<entry><literal>C-u</literal></entry>
		<entry>
		  Deletes all text between the cursor and the
		  beginning of the line.
		</entry>
	      </row>

	      <row>
		<entry><literal>DelBack</literal></entry>
		<entry><literal>backspace,C-h</literal></entry>
		<entry>
		  Deletes the previous character when entering text.
		</entry>
	      </row>

	      <row>
		<entry><literal>DelEOL</literal></entry>
		<entry><literal>C-k</literal></entry>
		<entry>
		  Deletes all text from the cursor to the end of the
		  line.
		</entry>
	      </row>

	      <row>
		<entry><literal>DelForward</literal></entry>
		<entry><literal>delete,C-d</literal></entry>
		<entry>
		  Deletes the character under the cursor when entering text.
		</entry>
	      </row>

	      <row>
		<entry><literal>Dependencies</literal></entry>
		<entry><literal>d</literal></entry>
		<entry>
		  Displays the dependencies of the currently selected
		  package.
		</entry>
	      </row>

	      <row>
		<entry><literal>DescriptionCycle</literal></entry>
		<entry><literal>i</literal></entry>
		<entry>
		  When browsing the package list, cycles through the
		  available views in the information area.
		</entry>
	      </row>

	      <row>
		<entry><literal>DescriptionDown</literal></entry>
		<entry><literal>z</literal></entry>
		<entry>
		  When browsing the package list, scrolls the
		  information area down one line.
		</entry>
	      </row>

	      <row>
		<entry><literal>DescriptionUp</literal></entry>
		<entry><literal>a</literal></entry>
		<entry>
		  When browsing the package list, scrolls the
		  information area up one line.
		</entry>
	      </row>

	      <row>
		<entry><literal>DoInstallRun</literal></entry>
		<entry><literal>g</literal></entry>
		<entry>
		  If not in a preview screen, display the preview
		  screen
		  <footnote>
		    <para>
		      unless <literal><link
		      linkend='configDisplay-Planned-Action'>Aptitude::Display-Planned-Action</link></literal>
		      is false.
		    </para>
		  </footnote>; if in a preview screen, perform an
		  <link linkend='secInstallRun'>install run.</link>
		</entry>
	      </row>

	      <row>
		<entry><literal>Down</literal></entry>
		<entry><literal>down,j</literal></entry>
		<entry>
		  Moves down: for instance, scrolls a text display
		  down or selects the next item in a list.
		</entry>
	      </row>

	      <row>
		<entry><literal>DpkgReconfigure</literal></entry>
		<entry><literal>R</literal></entry>
		<entry>
		  Runs <quote>dpkg-reconfigure</quote> on the currently selected
		  package.
		</entry>
	      </row>

	      <row>
		<entry><literal>DumpResolver</literal></entry>
		<entry><literal>*</literal></entry>
		<entry>
		  If packages are broken, writes the current state of
		  the problem-resolver to a file (for debugging
		  purposes).
		</entry>
	      </row>

	      <row>
		<entry><literal>EditHier</literal></entry>
		<entry><literal>E</literal></entry>
		<entry>
		  Opens the <!--TODO: link linkend='secHier'>
		  -->hierarchy editor.
		</entry>
	      </row>

	      <row>
		<entry><literal>End</literal></entry>
		<entry><literal>end,C-e</literal></entry>
		<entry>
		  Move to the end of the current display: to the
		  bottom of a list, or to the right of a text entry
		  field.
		</entry>
	      </row>

	      <row>
		<entry><literal>ExamineSolution</literal></entry>
		<entry><literal>e</literal></entry>
		<entry>
		  If some packages are broken and &aptitude; has
		  suggested a solution, display a dialog box with a
		  detailed description of the proposed solution.
		</entry>
	      </row>

	      <row>
		<entry><literal>ExpandAll</literal></entry>
		<entry><literal>[</literal></entry>
		<entry>
		  Expands the selected tree and all its children in a
		  hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>ExpandTree</literal></entry>
		<entry>No binding</entry>
		<entry>
		  Expands the selected tree in a hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>FirstSolution</literal></entry>
		<entry><literal>&lt;</literal></entry>
		<entry>
		  Select the first solution produced by the problem
		  resolver.
		</entry>
	      </row>

	      <row>
		<entry><literal>ForbidUpgrade</literal></entry>
		<entry><literal>F</literal></entry>
		<entry>
		  <link linkend='pkgCmdForbid'>Forbids</link> a
		  package from being upgraded to the currently
		  available version (or a particular version).
		</entry>
	      </row>

	      <row>
		<entry><literal>ForgetNewPackages</literal></entry>
		<entry><literal>f</literal></entry>
		<entry>
		  Discards all information about which packages are
		  <quote>new</quote> (causes the list of <quote>new</quote> packages to become
		  empty).
		</entry>
	      </row>

	      <row>
		<entry><literal>Help</literal></entry>
		<entry><literal>?</literal></entry>
		<entry>
		  Displays the on-line help screen.
		</entry>
	      </row>

	      <row>
		<entry><literal>HistoryNext</literal></entry>
		<entry><literal>down,C-n</literal></entry>
		<entry>
		  In a line editor with history, moves forwards in
		  the history.
		</entry>
	      </row>

	      <row>
		<entry><literal>HistoryPrev</literal></entry>
		<entry><literal>up,C-p</literal></entry>
		<entry>
		  In a line editor with history, moves backwards in
		  the history.
		</entry>
	      </row>

	      <row>
		<entry><literal>Hold</literal></entry>
		<entry><literal>=</literal></entry>
		<entry>
		  Places a package on <link
		  linkend='pkgCmdHold'>hold</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>Install</literal></entry>
		<entry><literal>+</literal></entry>
		<entry>
		  Flags a package for <link
		  linkend='pkgCmdInstall'>installation</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>InstallSingle</literal></entry>
		<entry><literal>I</literal></entry>
		<entry>
		  Marks a single package for installation; all other
		  packages are kept at their current version.
		</entry>
	      </row>

	      <row>
		<entry><literal>Keep</literal></entry>
		<entry><literal>:</literal></entry>
		<entry>
		  <link linkend='pkgCmdKeep'>Cancels</link> all
		  installation or removal requests and all holds for a
		  package.
		</entry>
	      </row>

	      <row>
		<entry><literal>LastSolution</literal></entry>
		<entry><literal>&lt;</literal></entry>
		<entry>
		  Select the last solution produced by the problem
		  resolver.
		</entry>
	      </row>

	      <row>
		<entry><literal>Left</literal></entry>
		<entry><literal>left,h</literal></entry>
		<entry>
		  Moves left: for instance, moves one menu to the left
		  in the menu bar, or moves the cursor to the left
		  when editing text.
		</entry>
	      </row>

	      <row>
		<entry><literal>LevelDown</literal></entry>
		<entry><literal>J</literal></entry>
		<entry>
		  In a hierarchical list, selects the next sibling of
		  the currently selected item (the next item at the
		  same level with the same parent).
		</entry>
	      </row>

	      <row>
		<entry><literal>LevelUp</literal></entry>
		<entry><literal>K</literal></entry>
		<entry>
		  In a hierarchical list, selects the previous sibling
		  of the currently selected item (the previous item at
		  the same level with the same parent).
		</entry>
	      </row>

	      <row>
		<entry><literal>MarkUpgradable</literal></entry>
		<entry><literal>U</literal></entry>
		<entry>
		  Attempts to upgrade all packages which are not held
		  back or forbidden from upgrading.
		</entry>
	      </row>

	      <row>
		<entry><literal>MineFlagSquare</literal></entry>
		<entry><literal>f</literal></entry>
		<entry>
		  In <link
		  linkend='secMinesweeper'>Minesweeper</link>, places
		  or removes a flag on a square.
		</entry>
	      </row>

	      <row>
		<entry><literal>MineLoadGame</literal></entry>
		<entry><literal>L</literal></entry>
		<entry>
		  Loads a <link
		  linkend='secMinesweeper'>Minesweeper</link> game.
		</entry>
	      </row>

	      <row>
		<entry><literal>MineSaveGame</literal></entry>
		<entry><literal>S</literal></entry>
		<entry>
		  Saves a <link
		  linkend='secMinesweeper'>Minesweeper</link> game.
		</entry>
	      </row>

	      <row>
		<entry><literal>MineSweepSquare</literal></entry>
		<entry>No binding</entry>
		<entry>
		  Sweeps around the current square in <link
		  linkend='secMinesweeper'>Minesweeper</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>MineUncoverSquare</literal></entry>
		<entry>No binding</entry>
		<entry>
		  Uncovers the current square in <link
		  linkend='secMinesweeper'>Minesweeper</link>
		</entry>
	      </row>

	      <row>
		<entry><literal>MineUncoverSweepSquare</literal></entry>
		<entry><literal>enter</literal></entry>
		<entry>
		  Uncovers the current square in <link
		  linkend='secMinesweeper'>Minesweeper</link> if it is
		  covered; otherwise, sweeps around it.
		</entry>
	      </row>

	      <row>
		<entry><literal>NextPage</literal></entry>
		<entry><literal>pagedown,C-f</literal></entry>
		<entry>
		  Moves the current display one page forward.
		</entry>
	      </row>

	      <row>
		<entry><literal>NextSolution</literal></entry>
		<entry><literal>.</literal></entry>
		<entry>
		  Advance the dependency resolver to the next solution.
		</entry>
	      </row>

	      <row>
		<entry><literal>No</literal></entry>
		<entry><literal>n</literal><footnoteref linkend='footnoteYesNoLocale'/></entry>
		<entry>
		  This key will select the <quote>no</quote> button in
		  yes/no dialog boxes.
		</entry>
	      </row>

	      <row>
		<entry><literal>Parent</literal></entry>
		<entry><literal>^</literal></entry>
		<entry>
		  Selects the parent of the selected item in a
		  hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>PrevPage</literal></entry>
		<entry><literal>pageup,C-b</literal></entry>
		<entry>
		  Moves the current display one page backward.
		</entry>
	      </row>

	      <row>
		<entry><literal>PrevSolution</literal></entry>
		<entry><literal>,</literal></entry>
		<entry>
		  Return the dependency resolver to the previous solution.
		</entry>
	      </row>

	      <row>
		<entry><literal>Purge</literal></entry>
		<entry><literal>_</literal></entry>
		<entry>
		  Flags the currently selected package to be <link
		  linkend='pkgCmdPurge'>purged</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>PushButton</literal></entry>
		<entry><literal>space,enter</literal></entry>
		<entry>
		  Activates the currently selected button, or toggles
		  a checkbox.
		</entry>
	      </row>

	      <row>
		<entry><literal>Quit</literal></entry>
		<entry><literal>q</literal></entry>
		<entry>
		  Close the current view.
		</entry>
	      </row>

	      <row>
		<entry><literal>QuitProgram</literal></entry>
		<entry><literal>Q</literal></entry>
		<entry>
		  Quit the entire program.
		</entry>
	      </row>

	      <row>
		<entry><literal>RejectBreakHolds</literal></entry>
		<entry></entry>
		<entry>
		  Reject all resolver actions that would break a hold;
		  equivalent to <link
		  linkend='menuResolverRejectBreakHolds'>&resolver-reject-break-holds;</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>Refresh</literal></entry>
		<entry><literal>C-l</literal></entry>
		<entry>
		  Redraws the screen from scratch.
		</entry>
	      </row>

	      <row>
		<entry><literal>Remove</literal></entry>
		<entry><literal>-</literal></entry>
		<entry>
		  Flags a package for <link linkend='pkgCmdRemove'>removal</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>ReInstall</literal></entry>
		<entry><literal>L</literal></entry>
		<entry>
		  Flags the currently selected package to be
		  <link linkend='pkgCmdReinstall'>reinstalled</link>.
		</entry>
	      </row>

	      <row>
		<entry><literal>RepeatSearchBack</literal></entry>
		<entry><literal>N</literal></entry>
		<entry>
		  Repeats the last search, but searches in the
		  opposite direction.
		</entry>
	      </row>

	      <row>
		<entry><literal>ReSearch</literal></entry>
		<entry><literal>n</literal></entry>
		<entry>
		  Repeats the last search.
		</entry>
	      </row>

	      <row>
		<entry><literal>ReverseDependencies</literal></entry>
		<entry><literal>r</literal></entry>
		<entry>
		  Displays packages which depend upon the currently
		  selected package.
		</entry>
	      </row>

	      <row>
		<entry><literal>Right</literal></entry>
		<entry><literal>right,l</literal></entry>
		<entry>
		  Moves right: for instance, moves one menu to the
		  right in the menu bar, or moves the cursor to the
		  right when editing text.
		</entry>
	      </row>

	      <row>
		<entry><literal>SaveHier</literal></entry>
		<entry><literal>S</literal></entry>
		<entry>
		  In the <!-- TODO: <link linkend='secHier'>
		  -->hierarchy editor, saves the current hierarchy.
		</entry>
	      </row>

	      <row>
		<entry><literal>Search</literal></entry>
		<entry><literal>/</literal></entry>
		<entry>
		  Activate the <quote>search</quote> function of the
		  currently active interface element.
		</entry>
	      </row>

	      <row>
		<entry><literal>SearchBack</literal></entry>
		<entry><literal>\</literal></entry>
		<entry>
		  Activate the <quote>search backwards</quote> function of the
		  currently active interface element.
		</entry>
	      </row>

	      <row>
		<entry><literal>SearchBroken</literal></entry>
		<entry><literal>b</literal></entry>
		<entry>
		  In a package tree, search for the next broken
		  package.
		</entry>
	      </row>

	      <row>
		<entry><literal>SetAuto</literal></entry>
		<entry><literal>M</literal></entry>
		<entry>
		  Marks the current package as having been <link
		  linkend='secAutoInstall'>automatically
		  installed</link>.
		</entry>
	      </row>

	      <row id='keyShowHideDescription'>
		<entry><literal>ShowHideDescription</literal></entry>
		<entry><literal>D</literal></entry>
		<entry>
		  In a package list, toggles whether the information
		  area is visible.
		</entry>
	      </row>

	      <row>
		<entry><literal>SolutionActionApprove</literal></entry>
		<entry><literal>a</literal></entry>
		<entry>
		  When viewing a solution, marks the currently
		  selected action as "approved" (it will be included
		  in future solutions whenever possible).
		</entry>
	      </row>

	      <row>
		<entry><literal>SolutionActionReject</literal></entry>
		<entry><literal>r</literal></entry>
		<entry>
		  When viewing a solution, marks the currently
		  selected action as "rejected" (future solutions will
		  not contain it).
		</entry>
	      </row>

	      <row>
		<entry><literal>ToggleExpanded</literal></entry>
		<entry><literal>enter</literal></entry>
		<entry>
		  Expands or collapses the currently selected tree in
		  a hierarchical list.
		</entry>
	      </row>

	      <row>
		<entry><literal>ToggleMenuActive</literal></entry>
		<entry><literal>C-m,f10,C-space</literal></entry>
		<entry>
		  Activates or deactivates the main menu.
		</entry>
	      </row>

	      <row>
		<entry><literal>Undo</literal></entry>
		<entry><literal>C-_,C-u</literal></entry>
		<entry>
		  Cancels the last action, up to when &aptitude; was
		  started OR the last time you update the package
		  lists or installed packages.
		</entry>
	      </row>

	      <row>
		<entry><literal>Up</literal></entry>
		<entry><literal>up,k</literal></entry>
		<entry>
		  Moves up: for instance, scrolls a text display
		  up or selects the previous item in a list.
		</entry>
	      </row>

	      <row>
		<entry><literal>UpdatePackageList</literal></entry>
		<entry><literal>u</literal></entry>
		<entry>
		  Updates the list of packages by fetching new lists
		  from the Internet if necessary.
		</entry>
	      </row>

	      <row>
		<entry><literal>Versions</literal></entry>
		<entry><literal>v</literal></entry>
		<entry>
		  Displays the available versions of the currently
		  selected package.
		</entry>
	      </row>

	      <row>
		<entry><literal>Yes</literal></entry>
		<entry>
		  <literal>y</literal>
		  <footnote id='footnoteYesNoLocale'>
		    <para>
		      This default may be different in different locales.
		    </para>
		  </footnote>
		</entry>
		<entry>
		  This key will select the <quote>Yes</quote> button
		  in yes/no dialog boxes.
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>
	  In addition to letter keys, number keys, and punctuation,
	  the following <quote>special</quote> keys can be bound:
	</para>

	<informaltable>
	  <tgroup cols='2'>
	    <thead>
	      <row>
		<entry>Key name</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal>a1</literal></entry>
		<entry>The A1 key.</entry>
	      </row>

	      <row>
		<entry><literal>a3</literal></entry>
		<entry>The A3 key.</entry>
	      </row>

	      <row>
		<entry><literal>b2</literal></entry>
		<entry>The B2 key.</entry>
	      </row>

	      <row>
		<entry><literal>backspace</literal></entry>
		<entry>The Backspace key.</entry>
	      </row>

	      <row>
		<entry><literal>backtab</literal></entry>
		<entry>The back-tab key</entry>
	      </row>

	      <row>
		<entry><literal>begin</literal></entry>
		<entry>The Begin key (not Home)</entry>
	      </row>

	      <row>
		<entry><literal>break</literal></entry>
		<entry>
		  The <quote>break</quote> key.
		</entry>
	      </row>

	      <row>
		<entry><literal>c1</literal></entry>
		<entry>The C1 key.</entry>
	      </row>

	      <row>
		<entry><literal>c3</literal></entry>
		<entry>The C3 key.</entry>
	      </row>

	      <row>
		<entry><literal>cancel</literal></entry>
		<entry>The Cancel key.</entry>
	      </row>

	      <row>
		<entry><literal>create</literal></entry>
		<entry>The Create key.</entry>
	      </row>

	      <row>
		<entry><literal>comma</literal></entry>
		<entry>
		  Comma (,) -- note that because commas are used to
		  list keys, this is the only way to bind to a comma.
		</entry>
	      </row>

	      <row>
		<entry><literal>command</literal></entry>
		<entry>The Command key.</entry>
	      </row>

	      <row>
		<entry><literal>copy</literal></entry>
		<entry>The Copy key.</entry>
	      </row>

	      <row>
		<entry><literal>delete</literal></entry>
		<entry>The Delete key.</entry>
	      </row>

	      <row>
		<entry><literal>delete_line</literal></entry>
		<entry>The <quote>delete line</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>down</literal></entry>
		<entry>The <quote>down</quote> arrow key.</entry>
	      </row>

	      <row>
		<entry><literal>end</literal></entry>
		<entry>The End key.</entry>
	      </row>

	      <row>
		<entry><literal>entry</literal></entry>
		<entry>The Enter key.</entry>
	      </row>

	      <row>
		<entry><literal>exit</literal></entry>
		<entry>The Exit key.</entry>
	      </row>

	      <row>
		<entry><literal>f1</literal>, <literal>f2</literal>, ..., <literal>f10</literal></entry>
		<entry>The F1 through F10 keys.</entry>
	      </row>

	      <row>
		<entry><literal>find</literal></entry>
		<entry>The Find key.</entry>
	      </row>

	      <row>
		<entry><literal>home</literal></entry>
		<entry>The Home key.</entry>
	      </row>

	      <row>
		<entry><literal>insert</literal></entry>
		<entry>The Insert key.</entry>
	      </row>

	      <row>
		<entry><literal>insert_exit</literal></entry>
		<entry>The <quote>insert exit</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>clear</literal></entry>
		<entry>The <quote>clear</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>clear_eol</literal></entry>
		<entry>The <quote>clear to end of line</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>clear_eos</literal></entry>
		<entry>The <quote>clear to end of screen</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>insert_line</literal></entry>
		<entry>The <quote>insert line</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>left</literal></entry>
		<entry>The <quote>left</quote> arrow key.</entry>
	      </row>

	      <row>
		<entry><literal>mark</literal></entry>
		<entry>The Mark key.</entry>
	      </row>

	      <row>
		<entry><literal>message</literal></entry>
		<entry>The Message key.</entry>
	      </row>

	      <row>
		<entry><literal>move</literal></entry>
		<entry>The Move key.</entry>
	      </row>

	      <row>
		<entry><literal>next</literal></entry>
		<entry>The Next key.</entry>
	      </row>

	      <row>
		<entry><literal>open</literal></entry>
		<entry>The Open key.</entry>
	      </row>

	      <row>
		<entry><literal>previous</literal></entry>
		<entry>The Previous key.</entry>
	      </row>

	      <row>
		<entry><literal>print</literal></entry>
		<entry>The Print key.</entry>
	      </row>

	      <row>
		<entry><literal>redo</literal></entry>
		<entry>The Redo key.</entry>
	      </row>

	      <row>
		<entry><literal>reference</literal></entry>
		<entry>The Reference key.</entry>
	      </row>

	      <row>
		<entry><literal>refresh</literal></entry>
		<entry>The Refresh key.</entry>
	      </row>

	      <row>
		<entry><literal>replace</literal></entry>
		<entry>The Replace key.</entry>
	      </row>

	      <row>
		<entry><literal>restart</literal></entry>
		<entry>The Restart key.</entry>
	      </row>

	      <row>
		<entry><literal>resume</literal></entry>
		<entry>The Resume key.</entry>
	      </row>

	      <row>
		<entry><literal>return</literal></entry>
		<entry>The Return key.</entry>
	      </row>

	      <row>
		<entry><literal>right</literal></entry>
		<entry>The <quote>right</quote> arrow key.</entry>
	      </row>

	      <row>
		<entry><literal>save</literal></entry>
		<entry>The Save key.</entry>
	      </row>

	      <row>
		<entry><literal>scrollf</literal></entry>
		<entry>The <quote>scroll forward</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>scrollr</literal></entry>
		<entry>The <quote>scroll backwards</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>select</literal></entry>
		<entry>The Select key.</entry>
	      </row>

	      <row>
		<entry><literal>suspend</literal></entry>
		<entry>The Suspend key.</entry>
	      </row>

	      <row>
		<entry><literal>pagedown</literal></entry>
		<entry>The <quote>Page Down</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>pageup</literal></entry>
		<entry>The <quote>Page Up</quote> key.</entry>
	      </row>

	      <row>
		<entry><literal>space</literal></entry>
		<entry>The Space key</entry>
	      </row>

	      <row>
		<entry><literal>tab</literal></entry>
		<entry>The Tab key</entry>
	      </row>

	      <row>
		<entry><literal>undo</literal></entry>
		<entry>The Undo key.</entry>
	      </row>

	      <row>
		<entry><literal>up</literal></entry>
		<entry>The <quote>up</quote> arrow key.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>
	  In addition to binding keys globally, it is possible to
	  change key bindings for one particular part (or
	  <firstterm>domain</firstterm>) of &aptitude;: for instance,
	  to make Tab the equivalent of the right arrow key in menu
	  bars, set
	  <literal>Aptitude::UI::Keybindings::Menubar::Right</literal>
	  to <quote><literal>tab,right</literal></quote>.  The
	  following domains are available:
	</para>

	<informaltable colsep='0' frame='all'>
	  <tgroup cols='2'>
	    <thead>
	      <row>
		<entry>Domain</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal>EditLine</literal></entry>
		<entry>
		   Used by line-editing widgets, such as the entry
		   field in a <quote>search</quote> dialog.
		</entry>
	      </row>

	      <row>
		<entry><literal>Menu</literal></entry>
		<entry>
		  Used by drop-down menus.
		</entry>
	      </row>

	      <row>
		<entry><literal>Menubar</literal></entry>
		<entry>
		  Used by the menu bar at the top of the screen.
		</entry>
	      </row>

	      <row>
		<entry><literal>Minesweeper</literal></entry>

		<entry>
		  Used by the <link
		  linkend='secMinesweeper'>Minesweeper</link> mode.
		</entry>
	      </row>

	      <row>
		<entry><literal>MinibufChoice</literal></entry>

		<entry>
		  Used by the multiple-choice prompts that appear if
		  you have chosen to have some prompts appear in the
		  status line.
		</entry>
	      </row>

	      <row>
		<entry><literal>Pager</literal></entry>

		<entry>
		  Used when displaying a file on disk (for instance,
		  the help text).
		</entry>
	      </row>

	      <row>
		<entry><literal>PkgNode</literal></entry>

		<entry>
		  Used by packages, trees of packages, package
		  versions, and package dependencies when they appear
		  in package lists.
		</entry>
	      </row>

	      <row>
		<entry><literal>PkgTree</literal></entry>

		<entry>
		  Used by package lists.
		</entry>
	      </row>

	      <row>
		<entry><literal>Table</literal></entry>

		<entry>
		  Used by tables of widgets (for instance, dialog boxes).
		</entry>
	      </row>

	      <row>
		<entry><literal>TextLayout</literal></entry>

		<entry>
		  Used by formatted text displays, such as package
		  descriptions.
		</entry>
	      </row>

	      <row>
		<entry><literal>Tree</literal></entry>

		<entry>
		  Used by all tree displays (including package lists,
		  for which it can be overridden by
		  <literal>PkgTree</literal>).
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </section>

      <section id='secStyle'>
	<title>Customizing text colors and styles</title>

	<para>
	  The colors and visual styles used by &aptitude; to display
	  text can be extensively customized.  Each visual element has
	  an associated <quote>style</quote>, which describes the
	  particular colors and visual attributes that will be used to
	  display that element.  Styles take the form of a list of
	  color and attribute settings.  This list is not necessarily
	  exhaustive; if some colors or attributes are not explicitly
	  specified, their values will be taken from the surrounding
	  visual context.  In fact, most visual elements have an
	  <quote>empty</quote> style by default.
	</para>

	<para>
	  You can change the contents of a style by creating a
	  configuration group of the same name in the &apt; or
	  &aptitude; configuration file.  For instance, the
	  <quote><literal>MenuBorder</literal></quote> style is used
	  to draw the visual border around drop-down menus.  By
	  default, this border is drawn bold and white-on-blue.
	  Placing the following text in the configuration file would
	  change it to white-on-cyan:
	</para>

	<screen>Aptitude::UI::Styles {
  MenuBorder {fg white; bg cyan; set bold;};
};</screen>

	<para>
	  As you can see, a style's configuration group consists of a
	  sequence of instructions.  The general classes of
	  instructions are:
	</para>

	<variablelist>
	  <varlistentry>
	    <term><literal>fg</literal> <replaceable>color</replaceable></term>
	    <listitem>
	      <para>
		Sets the text foreground to the given
		<replaceable>color</replaceable>.  See below for a
		list of the colors known to &aptitude;.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>bg</literal> <replaceable>color</replaceable></term>
	    <listitem>
	      <para>
		Sets the text background to the given
		<replaceable>color</replaceable>.  See below for a
		list of the colors known to &aptitude;.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>set</literal> <replaceable>attribute</replaceable></term>

	    <listitem>
	      <para>
		Enables the given text
		<replaceable>attribute</replaceable>.  See below for a
		list of the text attributes known to &aptitude;.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>clear</literal> <replaceable>attribute</replaceable></term>

	    <listitem>
	      <para>
		Disables the given text
		<replaceable>attribute</replaceable>.  See below for a
		list of the text attributes known to &aptitude;.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>flip</literal> <replaceable>attribute</replaceable></term>

	    <listitem>
	      <para>
		Toggles the given text
		<replaceable>attribute</replaceable>: if it is enabled
		in the surrounding element, it will be disabled, and
		vice versa.  See below for a list of the text
		attributes known to &aptitude;.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<para>
	  The colors that &aptitude; recognizes are <literal>black</literal>,
	  <literal>blue</literal>, <literal>cyan</literal>,
	  <literal>green</literal>, <literal>magenta</literal>,
	  <literal>red</literal>, <literal>white</literal>, and
	  <literal>yellow</literal>
	  <footnote>
	    <para>
	      On some terminals, a <quote>yellow</quote> background
	      will actually come out brown.
	    </para>
	  </footnote>.  In addition, you may specify
	  <literal>default</literal> in place of a background color to
	  use the default terminal background (this could be the
	  default color, an image file, or even
	  <quote>transparent</quote>).  The styles that &aptitude;
	  recognizes are:
	</para>

	<variablelist>
	  <varlistentry>
	    <term><literal>blink</literal></term>
	    <listitem>
	      <para>
		Enables blinking text.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>bold</literal></term>
	    <listitem>
	      <para>
		Makes the foreground color of the text (or the
		background if reverse video is enabled) brighter.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>dim</literal></term>
	    <listitem>
	      <para>
		May cause text to be extra-dim on some terminals.  No
		effect has been observed on common Linux terminals.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>reverse</literal></term>
	    <listitem>
	      <para>
		Swaps the foreground and background colors.  Many
		visual elements flip this attribute to perform common
		highlighting tasks.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>standout</literal></term>

	    <listitem>
	      <para>
		This enables <quote>the best highlighting mode of the
		terminal</quote>.  In xterms it is similar, but
		not idential to, reverse video; behavior on other
		terminals may vary.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>underline</literal></term>

	    <listitem>
	      <para>
		Enables underlined text.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<para>
	  You can select several attributes at once by separating them
	  with commas; for instance, <literal>set
	  bold,standout;</literal>.
	</para>

	<note>
	  <para>
	    As hinted at above, the interpretation of both styles and
	    text attributes is highly terminal-dependent.  You may
	    need to experiment a bit to find out exactly what some
	    settings do on your terminal.
	  </para>
	</note>

	<para>
	  The following styles can be customized in &aptitude;:
	</para>

	<figure id='figStyles'>
	  <title>Customizable styles in &aptitude;</title>

	  <informaltable>
	    <tgroup cols='3'>
	      <thead>
		<row>
		  <entry>Style</entry>
		  <entry>Default</entry>
		  <entry>Description</entry>
		</row>
	      </thead>

	      <tbody>
		<row>
		  <entry><literal>Bullet</literal></entry>
		  <entry><literal>fg yellow; set bold;</literal></entry>
		  <entry>
		    The style of the bullets in bulleted lists.
		  </entry>
		</row>

		<row>
		  <entry><literal>ChangelogNewerVersion</literal></entry>
		  <entry><literal>set bold;</literal></entry>
		  <entry>
		    The style of newer versions of the package in the
		    changelog view.  Note that &aptitude; will only
		    highlight newer versions of the package if you
		    have the package libparse-debianchangelog-perl
		    installed.
		  </entry>
		</row>

		<row id='colorDefaultWidgetBackground'>
		  <entry><literal>Default</literal></entry>
		  <entry><literal>fg white; bg black;</literal></entry>
		  <entry>
		    The basic style of the screen.
		  </entry>
		</row>

		<row>
		  <entry><literal>DepBroken</literal></entry>
		  <entry><literal>fg black; bg red;</literal></entry>
		  <entry>
		    The style of unfulfilled dependencies.
		  </entry>
		</row>

		<row>
		  <entry><literal>DisabledMenuEntry</literal></entry>
		  <entry><literal>fg black; bg blue; set dim;</literal></entry>
		  <entry>
		    The style of menu entries that are disabled and
		    cannot be used.
		  </entry>
		</row>

		<row>
		  <entry><literal>DownloadHit</literal></entry>
		  <entry><literal>fg black; bg green;</literal></entry>
		  <entry>
		    The style used to indicate that a file was
		    <quote>hit</quote>: i.e., it has not changed since
		    the last time it was downloaded.
		  </entry>
		</row>

		<row>
		  <entry><literal>DownloadProgress</literal></entry>
		  <entry><literal>fg blue; bg yellow;</literal></entry>
		  <entry>
		    The style of the progress indicator for a
		    download.
		  </entry>
		</row>

		<row>
		  <entry><literal>EditLine</literal></entry>
		  <entry><literal>fg white; bg black; clear reverse;</literal></entry>
		  <entry>
		    The style of line editors (for instance, the entry
		    in the <quote>Search</quote> dialog).
		  </entry>
		</row>

		<row>
		  <entry><literal>Error</literal></entry>
		  <entry><literal>fg white; bg red; set bold;</literal></entry>
		  <entry>The style of error messages.</entry>
		</row>


		<row>
		  <entry><literal>Header</literal></entry>
		  <entry><literal>fg white; bg blue; set bold;</literal></entry>
		  <entry>
		    The style of screen headers.
		  </entry>
		</row>

		<row>
		  <entry><literal>HighlightedMenuBar</literal></entry>
		  <entry><literal>fg white; bg blue; set bold,reverse;</literal></entry>
		  <entry>
		    The style of the currently selected menu name in
		    the menu bar.
		  </entry>
		</row>

		<row>
		  <entry><literal>HighlightedMenuEntry</literal></entry>
		  <entry><literal>fg white; bg blue; set bold,reverse;</literal></entry>
		  <entry>
		    The style of the currently selected choice in a
		    menu.
		  </entry>
		</row>

		<row>
		  <entry><literal>MediaChange</literal></entry>
		  <entry><literal>fg yellow; bg red; set bold;</literal></entry>
		  <entry>
		    The style of the dialog used to ask the user to
		    insert a new CD.
		  </entry>
		</row>

		<row>
		  <entry><literal>MenuBar</literal></entry>
		  <entry><literal>fg white; bg blue; set bold;</literal></entry>

		  <entry>
		    The style of the menu bar.
		  </entry>
		</row>

		<row>
		  <entry><literal>MenuBorder</literal></entry>
		  <entry><literal>fg white; bg blue; set bold;</literal></entry>
		  <entry>
		    The style of the borders that surround a drop-down
		    menu.
		  </entry>
		</row>

		<row>
		  <entry><literal>MenuEntry</literal></entry>
		  <entry><literal>fg white; bg blue;</literal></entry>
		  <entry>
		    The style of each entry in a drop-down menu.
		  </entry>
		</row>

		<row>
		  <entry><literal>MineBomb</literal></entry>
		  <entry><literal>fg red; set bold;</literal></entry>
		  <entry>
		    The style of bombs in <link
		    linkend='secMinesweeper'>Minesweeper</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>MineBorder</literal></entry>
		  <entry><literal>set bold;</literal></entry>
		  <entry>
		    The style of the border drawn around a <link
		    linkend='secMinesweeper'>Minesweeper</link> board.
		  </entry>
		</row>

		<row>
		  <entry><literal>MineFlag</literal></entry>
		  <entry><literal>fg red; set bold;</literal></entry>
		  <entry>
		    The style of flags in <link
		    linkend='secMinesweeper'>Minesweeper</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>MineNumber</literal><replaceable>N</replaceable></entry>
		  <entry>Various</entry>
		  <entry>
		    The style of the number
		    <replaceable>N</replaceable> in Minesweeper;
		    <replaceable>N</replaceable> may range from 0 to
		    8.
		  </entry>
		</row>

		<row>
		  <entry><literal>MultiplexTab</literal></entry>
		  <entry><literal>fg white; bg blue;</literal></entry>
		  <entry>
		    The color used to display <quote>tabs</quote>
		    other than the currently selected one.
		  </entry>
		</row>

		<row>
		  <entry><literal>MultiplexTabHighlighted</literal></entry>
		  <entry><literal>fg blue; bg white;</literal></entry>
		  <entry>
		    The color used to display the currently selected
		    <quote>tab</quote>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgBroken</literal></entry>
		  <entry><literal>fg red; flip reverse;</literal></entry>
		  <entry>
		    The style of packages in the package list which
		    have unfulfilled dependencies.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgBrokenHighlighted</literal></entry>
		  <entry><literal>fg red;</literal></entry>
		  <entry>
		    The style of highlighted packages in the package
		    list which have unfulfilled dependencies.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgNotInstalled</literal></entry>
		  <entry></entry>
		  <entry>
		    The style of packages which are not currently
		    installed and will not be installed.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgNotInstalledHighlighted</literal></entry>
		  <entry></entry>
		  <entry>
		    The style of highlighted packages which are not
		    currently installed and will not be installed.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgIsInstalled</literal></entry>
		  <entry><literal>set bold;</literal></entry>
		  <entry>
		    The style of packages which are currently
		    installed and for which no actions are scheduled.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgIsInstalledHighlighted</literal></entry>
		  <entry><literal>set bold; flip reverse;</literal></entry>
		  <entry>
		    The style of highlighted packages which are
		    currently installed and for which no actions are
		    scheduled.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToDowngrade</literal></entry>
		  <entry><literal>set bold;</literal></entry>

		  <entry>
		    The style of packages in the package list which
		    will be downgraded.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToDowngradeHighlighted</literal></entry>
		  <entry><literal>set bold; flip reverse</literal></entry>

		  <entry>
		    The style of highlighted packages in the package
		    list which will be downgraded.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToHold</literal></entry>
		  <entry><literal>fg white; flip reverse;</literal></entry>
		  <entry>
		    The style of packages in the package list which
		    are <link linkend='pkgCmdHold'>on hold</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToHoldHighlighted</literal></entry>
		  <entry><literal>fg white;</literal></entry>
		  <entry>
		    The style of highlighted packages in the package
		    list which are <link linkend='pkgCmdHold'>on
		    hold</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToInstall</literal></entry>
		  <entry><literal>fg green; flip reverse;</literal></entry>
		  <entry>
		    The style of packages in the package list which
		    are being <link
		    linkend='pkgCmdInstall'>installed</link> (not
		    upgraded) or <link
		    linkend='pkgCmdReinstall'>reinstalled</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToInstallHighlighted</literal></entry>
		  <entry><literal>fg green;</literal></entry>
		  <entry>
		    The style of highlighted packages in the package
		    list which are being <link
		    linkend='pkgCmdInstall'>installed</link> (not
		    upgraded) or <link
		    linkend='pkgCmdReinstall'>reinstalled</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToRemove</literal></entry>
		  <entry><literal>fg magenta; flip reverse;</literal></entry>
		  <entry>
		    The style of packages in the package list which
		    will be <link
		    linkend='pkgCmdRemove'>removed</link> or <link
		    linkend='pkgCmdPurge'>purged</link>.
		  </entry>
		</row>
		<row>
		  <entry><literal>PkgToRemoveHighlighted</literal></entry>
		  <entry><literal>fg magenta;</literal></entry>
		  <entry>
		    The style of highlighted packages in the package
		    list which will be <link
		    linkend='pkgCmdRemove'>removed</link> or <link
		    linkend='pkgCmdPurge'>purged</link>.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToUpgrade</literal></entry>
		  <entry><literal>fg cyan; flip reverse;</literal></entry>
		  <entry>
		    The style of packages in the package list which
		    will be upgraded.
		  </entry>
		</row>

		<row>
		  <entry><literal>PkgToUpgradeHighlighted</literal></entry>
		  <entry><literal>fg cyan;</literal></entry>
		  <entry>
		    The style of highlighted packages in the package
		    list which will be upgraded.
		  </entry>
		</row>

		<row>
		  <entry><literal>Progress</literal></entry>
		  <entry><literal>fg blue; bg yellow;</literal></entry>
		  <entry>
		    The style of progress indicators such as the one
		    that appears while the package cache is being
		    loaded.
		  </entry>
		</row>

		<row>
		  <entry><literal>SolutionActionApproved</literal></entry>
		  <entry><literal>bg green;</literal></entry>
		  <entry>
		    The style of approved actions in a solution.
		  </entry>
		</row>

		<row>
		  <entry><literal>SolutionActionRejected</literal></entry>
		  <entry><literal>bg red;</literal></entry>
		  <entry>
		    The style of rejected actions in a solution.
		  </entry>
		</row>

		<row id='colorScreenStatusColor'>
		  <entry><literal>Status</literal></entry>
		  <entry><literal>fg white; bg blue; set bold;</literal></entry>
		  <entry>
		    The style of status lines at the bottom of the
		    screen.
		  </entry>
		</row>

		<row id='colorTreeBackground'>
		  <entry><literal>TreeBackground</literal></entry>
		  <entry></entry>
		  <entry>
		    The basic color of all visual lists and trees.
		  </entry>
		</row>

		<row id='colorTrustWarning'>
		  <entry><literal>TrustWarning</literal></entry>
		  <entry><literal>fg red; bg black; set bold;</literal></entry>
		  <entry>
		    The color used to display warnings about <link
		    linkend='secTrust'>package trust</link>.
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</figure>
      </section>

      <section id='secDisplayLayout'>
	<title>Customizing the display layout</title>

	<para>
	  It is possible to rearrange the &aptitude; package list by
	  making suitable modifications to the <link
	  linkend='secConfigFile'>configuration file</link>.
	</para>

	<section>
	  <title>Display elements</title>

	  <para>
	    The layout is stored in the configuration group
	    <literal>Aptitude::UI::Default-Package-View</literal>, and
	    consists of a list of display elements:
	  </para>

	  <synopsis><replaceable>Name</replaceable> <replaceable>Type</replaceable> {
  Row <replaceable>row</replaceable>;
  Column <replaceable>column</replaceable>;
  Width <replaceable>width</replaceable>;
  Height <replaceable>height</replaceable>;

  <replaceable>additional options...</replaceable>
};</synopsis>

          <para>
	    This creates a display element named
	    <replaceable>Name</replaceable>; the type of element
	    created is determined by <replaceable>Type</replaceable>.
	    The <literal><link
	    linkend='layoutRow'>Row</link></literal>, <literal><link
	    linkend='layoutColumn'>Column</link></literal>,
	    <literal><link
	    linkend='layoutWidth'>Width</link></literal>, and
	    <literal><link
	    linkend='layoutHeight'>Height</link></literal>
	    options must be present; they determine where the display
	    element is placed.  (see <link
	    linkend='secWidgetPlacement'>below</link> for a detailed
	    explanation of how display elements are arranged)
	  </para>

	  <para>
	    For examples of how to change the display layout, see the
	    <link linkend='secThemes'>theme</link> definitions in the
	    file
	    <filename>/usr/share/aptitude/aptitude-defaults</filename>.
	  </para>

	  <para>
	    The following types of display elements are available:
	  </para>

	  <variablelist>

	    <varlistentry id='layoutDescription'>
	      <term><literal>Description</literal></term>

	      <listitem>
		<para>
		  This display element will contain the
		  <quote>information area</quote> (typically a
		  description of the currently selected package).
		</para>

		<para>
		  The option <literal><link
		  linkend='layoutPopUpDownKey'>PopUpDownKey</link></literal>
		  gives the name of a keyboard command which will
		  cause the display element to be shown or hidden.
		  For instance, setting this to <literal><link
		  linkend='keyShowHideDescription'>ShowHideDescription</link></literal>
		  will give the current display element the same
		  behavior as the default information area.  The
		  option <literal><link
		  linkend='layoutPopUpDownKey'>PopUpDownLinked</link></literal>
		  gives the name of another display element; the
		  current element will be shown or hidden whenever the
		  other element is.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>MainWidget</literal></term>

	      <listitem>
		<para>
		  This is a placeholder for the <quote>main</quote>
		  display element: typically this is the list of
		  packages.  A display layout must contain exactly one
		  <literal>MainWidget</literal> element: no more, no
		  less.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutStatic'>
	      <term><literal>Static</literal></term>

	      <listitem>
		<para>
		  A region of the screen which displays some text,
		  possibly containing formatting codes as described in
		  <xref linkend='secDisplayFormat'/>.  The text to
		  display can be given in the <literal><link
		  linkend='layoutColumns'>Columns</link></literal>
		  option, or it can be stored in another configuration
		  variable specified by the <literal><link
		  linkend='layoutColumnsCfg'>ColumnsCfg</link></literal>
		  option.  The color of the text is determined by the
		  color named by the <literal><link
		  linkend='layoutColor'>Color</link></literal> option.
		</para>

		<para>
		  <literal>Static</literal> items can be displayed and
		  hidden in the same way as <literal><link
		  linkend='layoutDescription'>Description</link></literal>
		  items, using the <literal><link
		  linkend='layoutPopUpDownKey'>PopUpDownKey</link></literal>
		  and <literal><link
		  linkend='layoutPopUpDownLinked'>PopUpDownLinked</link></literal>
		  options.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</section>

	<section id='secWidgetPlacement'>
	  <title>Placement of display elements</title>

	  <para>
	    The display elements are arranged in a
	    <quote>table</quote>.  The upper-left corner of an element
	    is in the cell given by its <literal><link
	    linkend='layoutRow'>Row</link></literal> and
	    <literal><link
	    linkend='layoutColumn'>Column</link></literal>
	    options (typically starting from row 0 and column 0, but
	    this is not required).  The width of an element in cells
	    is given by its <literal><link
	    linkend='layoutWidth'>Width</link></literal>
	    option, and its height is given by its <literal><link
	    linkend='layoutHeight'>Height</link></literal>
	    option.
	  </para>

	  <para>
	    Once the display elements are arranged and have been given
	    an initial amount of space on the screen, there is likely
	    to be space left over.  If there is extra vertical space,
	    each row containing a display element whose <literal><link
	    linkend='layoutRowExpand'>RowExpand</link></literal>
	    option is <literal>true</literal> will be allocated a share
	    of the extra space; similarly, if there is extra
	    horizontal space, each column containing a display element
	    whose <literal><link
	    linkend='layoutColExpand'>ColExpand</link></literal>
	    option is <literal>true</literal> will be allocated a share
	    of the extra space.
	  </para>

	  <para>
	    In the event that there is not enough space, every row and
	    column whose widgets <emphasis>all</emphasis> have their
	    <literal><link
	    linkend='layoutRowShrink'>RowShrink</link></literal> or
	    <literal><link
	    linkend='layoutColShrink'>ColShrink</link></literal>
	    options set to <literal>true</literal> will be shrunk.  If
	    this is not enough, all rows and columns are shrunk to fit
	    into the available space.
	  </para>

	  <para>
	    If a display element is not expanded, but its row or
	    column is, its alignment is determined by the <literal><link
	    linkend='layoutRowAlign'>RowAlign</link></literal>
	    and <literal><link
	    linkend='layoutColAlign'>ColAlign</link></literal>
	    options.  Setting them to <literal>Left</literal>,
	    <literal>Right</literal>, <literal>Top</literal>,
	    <literal>Bottom</literal>, or <literal>Center</literal>
	    will tell &aptitude; where to place the element within the
	    row or column.
	  </para>

	  <para>
	    For instance, the following configuration group creates a
	    static element named
	    <quote><literal>Header</literal></quote>, which is three
	    cells wide and will expand horizontally but not
	    vertically.  It has the same color as other header lines
	    and uses the standard display format for header lines:
	  </para>

	  <screen>Header Static {
  Row 0;
  Column 0;
  Width 3;
  Height 1;

  ColExpand true;
  ColAlign Center;

  RowAlign Center;

  Color ScreenHeaderColor;
  ColumnsCfg HEADER;
};</screen>
	</section>

	<section>
	  <title>Display layout option reference</title>

	  <para>
	    The following options are available for display elements:
	  </para>

	  <variablelist>
	    <varlistentry id='layoutColAlign'>
	      <term><literal>ColAlign</literal>
	      <replaceable>alignment</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  <replaceable>alignment</replaceable> must be either
		  <literal>Left</literal>, <literal>Right</literal>,
		  or <literal>Center</literal>.  If the row containing
		  the current display element is wider than the
		  element itself and <literal><link
		  linkend='layoutColExpand'>ColExpand</link></literal>
		  is <literal>false</literal>, the element will be
		  placed within the row according to the value of
		  <replaceable>alignment</replaceable>.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>Left</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColExpand'>
	      <term><literal>ColExpand</literal>
	      <literal>true</literal>|<literal>false;</literal></term>

	      <listitem>
		<para>
		  If this option is set to <literal>true</literal>,
		  the column containing this display element will be
		  allocated a share of any extra horizontal space that
		  is available.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>false</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColor'>
	      <term><literal>Color</literal>
	      <replaceable>colorname</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  This option applies to <literal><link
		  linkend='layoutStatic'>Static</link></literal>
		  elements.  <replaceable>colorname</replaceable> is
		  the name of a color (for instance, <literal><link
		  linkend='colorScreenStatusColor'>ScreenStatusColor</link></literal>)
		  which should be used as the <quote>default</quote>
		  color for this display element.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal><link
		  linkend='colorDefaultWidgetBackground'>DefaultWidgetBackground</link></literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColShrink'>
	      <term><literal>ColShrink</literal>
	      <literal>true</literal>|<literal>false;</literal></term>

	      <listitem>
		<para>
		  If this option is set to <literal>true</literal> on
		  each element in a column and there is not enough
		  horizontal space, the column will be shrunk as
		  necessary to fit the available space.  Note that a
		  column may be shrunk even if
		  <literal>ColShrink</literal> is
		  <literal>false</literal>; it simply indicates that
		  &aptitude; should try shrinking a particular column
		  before shrinking other columns.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>false</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColumn'>
	      <term><literal>Column</literal> <replaceable>column</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  Specifies the leftmost
		  <replaceable>column</replaceable> containing this
		  display element.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColumns'>
	      <term><literal>Columns</literal> <replaceable>format</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  This option applies to <literal><link
		  linkend='layoutStatic'>Static</link></literal>
		  display elements for which the <literal><link
		  linkend='layoutColumnsCfg'>ColumnsCfg</link></literal>
		  option is not set.  It sets the displayed contents
		  of the status item; it is a format string as
		  described in <xref linkend='secDisplayFormat'/>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutColumnsCfg'>
	      <term><literal>ColumnsCfg</literal> <literal>HEADER</literal>|<literal>STATUS</literal>|<replaceable>name</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  This option applies to <literal><link
		  linkend='layoutStatic'>Static</link></literal>
		  display elements.  It sets the display format of the
		  current element to the value of another
		  configuration variable: if it is
		  <literal>HEADER</literal> or
		  <literal>STATUS</literal>, the options
		  <literal><link
		  linkend='configPackage-Header-Format'>Aptitude::UI::Package-Header-Format</link></literal>
		  and <literal><link
		  linkend='configPackage-Status-Format'>Aptitude::UI::Package-Status-Format</link></literal>,
		  repectively, are used; otherwise, the option
		  <replaceable>name</replaceable> is used.
		</para>

		<para>
		  If this option is not present, the value of the
		  <literal><link
		  linkend='layoutColumns'>Columns</link></literal> option is
		  used to control the contents of the static item.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutHeight'>
	      <term><literal>Height</literal>
	      <replaceable>height</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  Specifies the <replaceable>height</replaceable> of
		  the current display element.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutPopUpDownKey'>
	      <term><literal>PopUpDownKey</literal>
	      <replaceable>command</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  This option applies to <literal><link
		  linkend='layoutDescription'>Description</link></literal>
		  and <literal><link
		  linkend='layoutStatic'>Static</link></literal>
		  display elements.
		</para>

		<para>
		  <replaceable>command</replaceable> is the name of a
		  keyboard command (for instance, <literal><link
		  linkend='keyShowHideDescription'>ShowHideDescription</link></literal>).
		  When this key is pressed, the display element will
		  be hidden if it is visible, and displayed if it is
		  hidden.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutPopUpDownLinked'>
	      <term><literal>PopUpDownLinked
	      <replaceable>element</replaceable>;</literal></term>

	      <listitem>
		<para>
		  This option applies to <literal><link
		  linkend='layoutDescription'>Description</link></literal>
		  and <literal><link
		  linkend='layoutStatic'>Static</link></literal>
		  display elements.
		</para>

		<para>
		  <replaceable>element</replaceable> is the name of a
		  display element.  When
		  <replaceable>element</replaceable> is displayed, the
		  current element will also be displayed; when
		  <replaceable>element</replaceable> is hidden, the
		  current element will also be hidden.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutRow'>
	      <term><literal>Row</literal> <replaceable>row</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  Specifies the uppermost
		  <replaceable>row</replaceable> containing this
		  display element.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutRowAlign'>
	      <term><literal>RowAlign</literal>
	      <replaceable>alignment</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  <replaceable>alignment</replaceable> must be either
		  <literal>Top</literal>, <literal>Bottom</literal>,
		  or <literal>Center</literal>.  If the row containing
		  the current display element is taller than the
		  element itself and <literal><link
		  linkend='layoutRowExpand'>RowExpand</link></literal>
		  is <literal>false</literal>, the element will be
		  placed within the row according to the value of
		  <replaceable>alignment</replaceable>.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>Top</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutRowExpand'>
	      <term><literal>RowExpand</literal>
	      <literal>true</literal>|<literal>false;</literal></term>

	      <listitem>
		<para>
		  If this option is set to <literal>true</literal>,
		  the row containing this display element will be
		  allocated a share of any extra vertical space that
		  is available.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>false</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutRowShrink'>
	      <term><literal>RowShrink</literal>
	      <literal>true</literal>|<literal>false;</literal></term>

	      <listitem>
		<para>
		  If this option is set to <literal>true</literal> on
		  each element in a row and there is not enough
		  vertical space, the row will be shrunk as necessary
		  to fit the available space.  Note that a row may be
		  shrunk even if <literal>RowShrink</literal> is
		  <literal>false</literal>; it simply indicates that
		  &aptitude; should try shrinking a particular row
		  before shrinking other rows.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>false</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutVisible'>
	      <term><literal>Visible true|false;</literal></term>

	      <listitem>
		<para>
		  If set to <literal>false</literal>, this display
		  element will initially be hidden.  Presumably only
		  useful in conjunction with <literal><link
		  linkend='layoutPopUpDownKey'>PopUpDownKey</link></literal>
		  and/or <literal><link
		  linkend='layoutPopUpDownLinked'>PopUpDownLinked</link></literal>.
		</para>

		<para>
		  If this option is not present, it defaults to
		  <literal>true</literal>.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry id='layoutWidth'>
	      <term><literal>Width</literal>
	      <replaceable>width</replaceable><literal>;</literal></term>

	      <listitem>
		<para>
		  Specifies the <replaceable>width</replaceable> of
		  the current display element.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</section>
      </section>

      <section id='secConfigFile'>
	<title>Configuration file reference</title>

	<section>
	  <title>Configuration file format</title>

	  <para>
	    In its basic form, &aptitude;'s configuration file is a
	    list of options and their values.  Each line of the file
	    should have the form
	    <quote><replaceable>Option</replaceable>
	    <replaceable>Value</replaceable><literal>;</literal></quote>:
	    for instance, the following line in the configuration file
	    sets the option <literal><link
	    linkend='configTheme'>Aptitude::Theme</link></literal> to
	    <quote><literal>Dselect</literal></quote>.
	  </para>

	  <screen>Aptitude::Theme "Dselect";</screen>

	  <para>
	    An option can <quote>contain</quote> other options if they
	    are written in curly braces between the option and the
	    semicolon following it, like this:
	  </para>

	  <screen>Aptitude::UI {
  Package-Status-Format "";
  Package-Display-Format "";
};</screen>

	  <para>
	    An option that contains other options is sometimes called
	    a <firstterm>group</firstterm>.  In fact, the double
	    colons that appear in option names are actually a
	    shorthand way of indicating containment: the option
	    <literal>Aptitude::UI::Default-Grouping</literal> is
	    contained in the group <literal>Aptitude::UI</literal>,
	    which itself is contained in the group
	    <literal>Aptitude</literal>.  Thus, if you wanted to, you
	    could set this option to <literal>""</literal> as follows:
	  </para>

	  <screen>Aptitude {
  UI {
    Default-Grouping "";
  };
};</screen>

          <para>
	    For more information on the format of the configuration
	    file, see the manual page
	    <citerefentry><refentrytitle>apt.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
	  </para>
	</section>

	<section>
	  <title>Locations of configuration files</title>

	  <para>
	    &aptitude;'s configuration is read from the following
	    sources, in order:
	  </para>

	  <orderedlist>
            <listitem>
              <para>
                Configuration file options specified on the command-line.
              </para>
            </listitem>

	    <listitem>
	      <para>
		The user's configuration file,
		<filename>~/.aptitude/config</filename>.  This file is
		overwritten when the user modifies settings in the
		<link linkend='secOptionsMenu'>Options menu</link>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		The system configuration file,
		<filename>/etc/apt/apt.conf</filename>.
	      </para>
	    </listitem>

            <listitem>
              <para>
                The system configuration fragment files,
                <filename>/etc/apt/apt.conf.d/*</filename>.
              </para>
            </listitem>

            <listitem>
              <para>
                The file specified by the <literal>APT_CONFIG</literal>
                environment variable (if any).
              </para>
            </listitem>

	    <listitem>
	      <para>
		Default values stored in
		<filename>/usr/share/aptitude/aptitude-defaults</filename>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		Default values built into &aptitude;.
	      </para>
	    </listitem>
	  </orderedlist>

	  <para>
	    When an option is being checked, these sources are
	    searched in order, and the first one that provides a value
	    for the option is used.  For instance, setting an option
	    in <filename>/etc/apt/apt.conf</filename> will override
	    &aptitude;'s defaults for that option, but will not
	    override user settings in
	    <filename>~/.aptitude/config</filename>.
	  </para>
	</section>

	<section>
	  <title>Available configuration options</title>

	  <para>
	    The following configuration options are used by
	    &aptitude;.  Note that these are not the only available
	    configuration options; options used by the underlying
	    &apt; system are not listed here.  See the manual pages
	    <citerefentry><refentrytitle>apt</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	    and
	    <citerefentry><refentrytitle>apt.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	    for information on &apt; options.
	  </para>

	  <segmentedlist>
	    <?dbhtml list-presentation="list"?>

	    <segtitle>Option</segtitle>
	    <segtitle>Default</segtitle>
	    <segtitle>Description</segtitle>

	    <seglistitem id='configApt-AutoRemove-RecommendsImportant'>
	      <seg><literal>Apt::AutoRemove::RecommendsImportant</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, then
		&aptitude; will not consider packages to be unused
		(and thus will not automatically remove them) as long
		as any installed package recommends them, even if
		<literal><link
		linkend='configAptInstall-Recommends'>Apt::Install-Recommends</link></literal>
		is <literal>false</literal>.  For more information,
		see <xref linkend='secAutoInstall'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configApt-AutoRemove-SuggestsImportant'>
	      <seg><literal>Apt::AutoRemove::SuggestsImportant</literal></seg>
	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, then
		&aptitude; will not consider packages to be unused
		(and thus will not automatically remove them) as long
		as any installed package suggests them.  For more
		information, see <xref linkend='secAutoInstall'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configApt-Get-ListCleanup'>
	      <seg><literal>Apt::Get::List-Cleanup</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		A synonym for <literal><link
		linkend='configApt-ListCleanup'>Apt::List-Cleanup</link></literal>.
		If either of these options is set to
		<literal>false</literal>, &aptitude; will not delete
		old package list files after downloading a new set of
		package lists.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configApt-ListCleanup'>
	      <seg><literal>Apt::List-Cleanup</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		A synonym for <literal><link
		linkend='configApt-Get-ListCleanup'>Apt::Get::List-Cleanup</link></literal>.
		If either of these options is set to
		<literal>false</literal>, &aptitude; will not delete
		old package list files after downloading a new set of
		package lists.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAptInstall-Recommends'>
	      <seg><literal>Apt::Install-Recommends</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal> and
		<literal>Aptitude::Auto-Install</literal> is
		<literal>true</literal>, then whenever you mark a
		package for installation, &aptitude; will also mark
		the packages it recommends for installation.
		Furthermore, if this option is
		<literal>true</literal>, &aptitude; will not consider
		packages to be unused (and thus will not automatically
		remove them) as long as any installed package
		reommends them.  For more information, see <xref
		linkend='secAutoInstall'/> and <xref
		linkend='secImmediateResolution'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAllow-Null-Upgrade'>
	      <seg><literal>Aptitude::Allow-Null-Upgrade</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		Normally, if you try to start an install run when no
		actions will be performed, &aptitude; will print a
		warning and return to the package list.  If this
		option is <literal>true</literal>, &aptitude; will
		continue to the preview screen whenever there are
		upgradable packages, rather than displaying a reminder
		about the &actions-upgrade; command.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAlways-Use-Safe-Resolver'>
	      <seg><literal>Aptitude::Always-Use-Safe-Resolver</literal></seg>
	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, aptitude's
		command-line actions will always use a
		<quote>safe</quote> dependency resolver, as if <link
		linkend='cmdlineSafeResolver'><literal>--safe-resolver</literal></link>
		had been passed on the command line.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAutoclean-After-Update'>
	      <seg><literal>Aptitude::Autoclean-After-Update</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will clean up obsolete files (see <link
		linkend='menuCleanObs'>&actions-clean-obs;</link>)
		every time you update the package list.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAuto-Fix-Broken'>
	      <seg><literal>Aptitude::Auto-Fix-Broken</literal></seg>
	      <seg><literal>true</literal></seg>
	      <seg>
		If this option is <literal>false</literal>,
		&aptitude; will ask for permission before
		attempting to fix any broken packages.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAuto-Install'>
	      <seg><literal>Aptitude::Auto-Install</literal></seg>
	      <seg><literal>true</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will automatically attempt to fulfill the dependencies
		of a package when you mark a package to be installed
		or upgraded.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAuto-Install-Remove-Ok'>
	      <seg><literal>Aptitude::Auto-Install-Remove-Ok</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will automatically remove conflicting packages when
		you mark a package to be installed or upgraded.
		Normally these conflicts are flagged and you must
		handle them manually.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAuto-Upgrade'>
	      <seg><literal>Aptitude::Auto-Upgrade</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will automatically flag all
		upgradable packages for upgrade when the program
		starts, as if you had issued the command
		<link linkend='menuUpgrade'>&actions-upgrade;</link>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Always-Prompt'>
	      <seg><literal>Aptitude::CmdLine::Always-Prompt</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this is set, &aptitude;
		will always prompt before starting to install or
		remove packages, even if the prompt would
		normally be skipped.  This is equivalent to the
		<literal>-P</literal> command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Assume-Yes'>
	      <seg><literal>Aptitude::CmdLine::Assume-Yes</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will act as
		if the user had answered <quote>yes</quote> to
		every prompt, causing most prompts to be
		skipped.  This is equivalent to the
		<literal>-y</literal> command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Disable-Columns'>
	      <seg><literal>Aptitude::CmdLine::Disable-Columns</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is enabled, the results of command-line
		searches (performed via <literal>aptitude
		search</literal>) will not be formatted into
		fixed-width columns or truncated to the screen width.
		This is equivalent to the <link
		linkend='cmdlineOptionDisableColumns'><literal>--disable-columns</literal></link>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Download-Only'>
	      <seg><literal>Aptitude::CmdLine::Download-Only</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will
		download package files but not install them.
		This is equivalent to the <literal>-d</literal>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Fix-Broken'>
	      <seg><literal>Aptitude::CmdLine::Fix-Broken</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will be more
		aggressive when attempting to fix the
		dependencies of broken packages.  This is
		equivalent to the <literal>-f</literal>
		command-line option.
	      </seg>
	    </seglistitem>

            <seglistitem id='configCmdLine-Versions-Group-By'>
              <seg><literal>Aptitude::CmdLine::Versions-Group-By</literal></seg>

              <seg>
                Set to <literal>auto</literal>,
                <literal>none</literal>, <literal>package</literal>,
                or <literal>source-package</literal> to control
                whether and how the output of <link
                linkend='cmdlineVersions'><literal>aptitude
                versions</literal></link> is grouped.  Equivalent to
                the command-line option <link
                linkend='cmdlineGroupBy'><literal>--group-by</literal></link>
                (see its documentation for more description of what
                the values mean).
              </seg>
            </seglistitem>

	    <seglistitem id='configCmdLine-Ignore-Trust-Violations'>
	      <seg><literal>Aptitude::CmdLine::Ignore-Trust-Violations</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, causes &aptitude; to ignore the
		installation of <link linkend='secTrust'>untrusted
		packages</link>.  This is a synonym for
		<literal>Apt::Get::AllowUnauthenticated</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Package-Display-Format'>
	      <seg><literal>Aptitude::CmdLine::Package-Display-Format</literal></seg>
	      <seg><literal>%c%a%M %p# - %d#</literal></seg>

	      <seg>
		This is a format string, as described in <xref
		linkend='secDisplayFormat'/>, which is used to
		display the results of a command-line search.
		This is equivalent to the <literal>-F</literal>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Package-Display-Width'>
	      <seg><literal>Aptitude::CmdLine::Package-Display-Width</literal></seg>
	      <seg></seg>
	      <seg>
		This option gives the width in characters for
		which command-line search results should be
		formatted.  If it is empty (the default; ie,
		<literal>""</literal>), search results will be
		formatted for the current terminal size, or for
		an 80-column display if the terminal size cannot
		be determined.
	      </seg>
	    </seglistitem>

            <seglistitem id='configCmdLine-Progress-Percent-On-Right'>
              <seg><literal>Aptitude::CmdLine::Progress::Percent-On-Right</literal></seg>
              <seg><literal>false</literal></seg>
              <seg>
                This option controls whether command-line progress
                indicators display the percentage on the left-hand
                side of the screen, in the same style as &apt-get;, or
                on the right-hand side (the default).  This option
                does not affect download progress indicators.
              </seg>
            </seglistitem>

            <seglistitem id='configCmdLine-Progress-Retain-Completed'>
              <seg><literal>Aptitude::CmdLine::Progress::Retain-Completed</literal></seg>
              <seg><literal>false</literal></seg>
              <seg>
                If this value is <literal>false</literal>, then
                command-line progress indicators will be deleted and
                overwritten once the task they represent is completed.
                If it is <literal>true</literal>, then they will be
                left on the terminal.  This option does not affect
                download progress indicators.
              </seg>
            </seglistitem>

	    <seglistitem id='configCmdLine-Request-Strictness'>
	      <seg><literal>Aptitude::CmdLine::Request-Strictness</literal></seg>
	      <seg><literal>10000</literal></seg>
	      <seg>
		When run in command-line mode, if dependency problems
		are encountered, &aptitude; will add this value to the
		problem resolver score of each action that you
		explicitly request.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Resolver-Debug'>
	      <seg><literal>Aptitude::CmdLine::Resolver-Debug</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will print
		extremely verbose information while attempting to
		resolve broken dependencies.  As the name suggests,
		this option is primarily meant to aid in debugging the
		problem resolver.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Resolver-Dump'>
	      <seg><literal>Aptitude::CmdLine::Resolver-Dump</literal></seg>
	      <seg></seg>
	      <seg>
		In command-line mode, if it is necessary to resolve
		broken dependencies and this option is set to the name
		of a writable file, the resolver state will be dumped
		to this file before any calculations are undertaken.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Resolver-Show-Steps'>
	      <seg><literal>Aptitude::CmdLine::Resolver-Show-Steps</literal></seg>

	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, then a
		dependency solution will be displayed as a sequence of
		resolutions of individual dependencies; for instance,
		<quote><literal>wesnoth depends upon wesnoth-data (=
		1.2.4-1) -> installing wesnoth-data 1.2.4-1
		(unstable)</literal></quote>.  To toggle between the
		two display modes, press <keycap>o</keycap> at the
		prompt <quote><literal>Accept this solution?</literal></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Show-Deps'>
	      <seg><literal>Aptitude::CmdLine::Show-Deps</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will display
		a brief summary of the dependencies (if any)
		relating to a package's state.  This is
		equivalent to the <literal>-D</literal>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Show-Size-Changes'>
	      <seg><literal>Aptitude::CmdLine::Show-Size-Changes</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will display
		the expected change in the amount of space used
		by each package.  This is equivalent to the
		<literal>-Z</literal> command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Show-Summary'>
	      <seg><literal>Aptitude::CmdLine::Why-Display-Mode</literal></seg>
	      <seg><literal>no-summary</literal></seg>
	      <seg>
		This option sets the default value of the command-line
		argument <link
		linkend='cmdlineOptionShowSummary'><literal>--show-summary</literal></link>.
		See the documentation of <link
		linkend='cmdlineOptionShowSummary'><literal>--show-summary</literal></link>
		for a list of the allowed values of this option and
		their meanings.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Show-Versions'>
	      <seg><literal>Aptitude::CmdLine::Show-Versions</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will display
		the version of a package that is being installed
		or removed.  This is equivalent to the
		<literal>-V</literal> command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Show-Why'>
	      <seg><literal>Aptitude::CmdLine::Show-Why</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, if this option is
		<literal>true</literal>, &aptitude; will display the
		manually installed packages that require each
		automatically installed package, or the manually
		installed packages that cause a conflict with each
		automatically removed package.  This is equivalent to
		the <literal>-W</literal> command-line option and
		displays the same information you can access via
		<literal>aptitude why</literal> or by pressing
		<keycap>i</keycap> in a package list.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Version-Display-Format'>
	      <seg><literal>Aptitude::CmdLine::Version-Display-Format</literal></seg>
	      <seg><literal>%c%a%M %p# %t %i</literal></seg>

	      <seg>
		This is a format string, as described in <xref
		linkend='secDisplayFormat'/>, which is used to display
		the output of <literal>aptitude versions</literal>.
		This is equivalent to the <literal>-F</literal>
		command-line option.
	      </seg>
	    </seglistitem>

            <seglistitem id='configCmdLine-Versions-Show-Package-Names'>
              <seg><literal>Aptitude::CmdLine::Versions-Show-Package-Names</literal></seg>

              <seg>
                Set to <literal>always</literal>,
                <literal>auto</literal>, or <literal>never</literal>
                to control when package names are displayed in the
                output of <link
                linkend='cmdlineVersions'><literal>aptitude
                versions</literal></link>.  Equivalent to the
                command-line option <link
                linkend='cmdlineShowPackageNames'><literal>--show-package-names</literal></link>
                (see its documentation for more description of what
                the values mean).
              </seg>
            </seglistitem>

	    <seglistitem id='configSafe-Resolver-Show-Resolver-Actions'>
	      <seg><literal>Aptitude::Safe-Resolver::Show-Resolver-Actions</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is enabled, then when the
		<quote>safe</quote> dependency resolver has been
		activated via <link
		linkend='cmdlineSafeResolver'><literal>--safe-resolver</literal></link>
		or because the command-line action is <link
		linkend='manpageSafeUpgrade'><literal>safe-upgrade</literal></link>,
		it will display a summary of the actions taken by the
		resolver before showing the installation preview.
		Equivalent to the command-line option <link
		linkend='cmdlineOptionShowResolverActions'><literal>--show-resolver-actions</literal></link>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configScreenshotIncrementalLoadLimit'>
	      <seg><literal>Aptitude::Screenshot::IncrementalLoadLimit</literal></seg>
	      <seg><literal>16384</literal></seg>

	      <seg>
		The minimum size in bytes at which &aptitude; will begin
		to display screenshots incrementally.  Below this
		size, screenshots will not appear until they are fully
		downloaded.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>Aptitude::Screenshot::Cache-Max</literal></seg>
	      <seg><literal>4194304</literal></seg>

	      <seg>
		The maximum number of bytes of screenshot data that
		&aptitude; will store in memory for screenshots that are
		not currently being displayed.  The default is four
		megabytes.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Simulate'>
	      <seg><literal>Aptitude::CmdLine::Simulate</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		<emphasis>This option is deprecated; use
		<literal><link
		linkend='configSimulate'>Aptitude::Simulate</link></literal>
		instead.</emphasis> In command-line mode, causes
		&aptitude; to just display the actions that would be
		performed (rather than actually performing them); in
		the visual interface, causes &aptitude; to start in
		read-only mode regardless of whether you are &root; or
		not.  This is equivalent to the <literal>-s</literal>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Verbose'>
	      <seg><literal>Aptitude::CmdLine::Verbose</literal></seg>
	      <seg><literal>0</literal></seg>
	      <seg>
		This controls how verbose the command-line mode
		of &aptitude; is.  Every occurrence of the
		<literal>-v</literal> command-line option adds 1
		to this value.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configCmdLine-Visual-Preview'>
	      <seg><literal>Aptitude::CmdLine::Visual-Preview</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will enter its visual mode to display
		the preview of an installation run and to
		download packages.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDelete-Unused'>
	      <seg><literal>Aptitude::Delete-Unused</literal></seg>
	      <seg><literal>true</literal></seg>
	      <seg>
		If this option is <literal>true</literal>,
		automatically installed packages which are no
		longer required will be automatically removed.
		For more information, see <xref
		linkend='secAutoInstall'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDelete-Unused-Pattern'>
	      <seg><literal>Aptitude::Delete-Unused-Pattern</literal></seg>
	      <seg></seg>
	      <seg>
		Deprecated alias for <literal><link
		linkend='configKeep-Unused-Pattern'>Aptitude::Keep-Unused-Pattern</link></literal>.
		If <literal>Aptitude::Keep-Unused-Pattern</literal> is
		unset or set to an empty string, the value of this
		configuration option will override it.  Otherwise,
		<literal>Aptitude::Delete-Unused-Pattern</literal> is
		ignored.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDisplay-Planned-Action'>
	      <seg><literal>Aptitude::Display-Planned-Action</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will display a preview screen before
		actually carrying out the actions you have
		requested.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configForget-New-On-Install'>
	      <seg><literal>Aptitude::Forget-New-On-Install</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will clear the list of new packages
		whenever you install, upgrade, or remove
		packages, as if you had issued the command
		&actions-forget;.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configForget-New-On-Update'>
	      <seg><literal>Aptitude::Forget-New-On-Update</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will clear the list of new packages
		whenever the package list is updated, as if you
		had issued the command &actions-forget;.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configGet-Root-Command'>
	      <seg><literal>Aptitude::Get-Root-Command</literal></seg>

	      <seg><literal>su:/bin/su</literal></seg>

	      <seg>
		This option sets the external command that &aptitude;
		will use to switch to the &root; user (see <xref
		linkend='secBecomingRoot'/>).  It has the form
		<literal><replaceable>protocol</replaceable>:<replaceable>command</replaceable></literal>.
		<replaceable>protocol</replaceable> must be either
		<literal>su</literal> or <literal>sudo</literal>; it
		determines how &aptitude; invokes the program when it
		wants to gain &root; privileges.  If
		<replaceable>protocol</replaceable> is
		<literal>su</literal>, then
		<quote><literal><replaceable>command</replaceable> -c
		<replaceable>arguments</replaceable></literal></quote> is used
		to become &root;; otherwise, &aptitude; uses
		<quote><literal><replaceable>command</replaceable>
		<replaceable>arguments</replaceable></literal></quote>.  The
		first word in <replaceable>command</replaceable> is
		the name of the program that should be invoked;
		remaining words are treated as arguments to that
		program.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configIgnore-Old-Tmp'>
	      <seg><literal>Aptitude::Ignore-Old-Tmp</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		Old versions of &aptitude; created a directory
		<filename>~/.aptitude/.tmp</filename> which is no
		longer necessary.  If the directory exists and
		<literal>Aptitude::Ignore-Old-Tmp</literal> is
		<literal>true</literal>, &aptitude; will ask you
		whether to remove this directory.  This option is
		automatically set to <literal>true</literal> after you
		reply.  On the other hand, if the directory does not
		exist, this option is set to <literal>false</literal>
		so that you will be notified if it reappears.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configIgnore-Recommends-Important'>
	      <seg><literal>Aptitude::Ignore-Recommends-Important</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		In previous versions of &aptitude;, the setting
		<literal>Aptitude::Recommends-Important</literal>
		caused recommendations to be installed automatically,
		the same way that <literal><link
		linkend='configAptInstall-Recommends'>Apt::Install-Recommends</link></literal>
		does today.  If this option is set to
		<literal>false</literal> and
		<literal>Aptitude::Recommends-Important</literal> is
		also set to <literal>false</literal>, &aptitude; will
		set <literal><link
		linkend='configAptInstall-Recommends'>Apt::Install-Recommends</link></literal>
		to <literal>false</literal> and set
		<literal>Aptitude::Ignore-Recommends-Important</literal>
		to <literal>true</literal> on startup.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configKeep-Recommends'>
	      <seg><literal>Aptitude::Keep-Recommends</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		This is an obsolete option; use <literal><link
		linkend='configApt-AutoRemove-RecommendsImportant'>Apt::AutoRemove::Recommends-Important</link></literal>
		instead.  Setting this option to
		<literal>true</literal> has the same effect as setting
		<literal><link
		linkend='configApt-AutoRemove-RecommendsImportant'>Apt::AutoRemove::Recommends-Important</link></literal>
		to <literal>true</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configKeep-Suggests'>
	      <seg><literal>Aptitude::Keep-Suggests</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		This is an obsolete option; use <literal><link
		linkend='configApt-AutoRemove-SuggestsImportant'>Apt::AutoRemove::Suggests-Important</link></literal>
		instead.  Setting this option to
		<literal>true</literal> has the same effect as setting
		<literal><link
		linkend='configApt-AutoRemove-SuggestsImportant'>Apt::AutoRemove::Suggests-Important</link></literal>
		to <literal>true</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configKeep-Unused-Pattern'>
	      <seg><literal>Aptitude::Keep-Unused-Pattern</literal></seg>
	      <seg></seg>
	      <seg>
		If <literal><link
		linkend='configDelete-Unused'>Aptitude::Delete-Unused</link></literal>
		is <literal>true</literal>, only unused packages which
		do not match this pattern (see
		<xref linkend='secSearchPatterns'/>) will be removed.
		If this option is set to an empty string (the
		default), all unused packages will be removed.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configLockFile'>
	      <seg><literal>Aptitude::LockFile</literal></seg>

	      <seg><literal>/var/lock/aptitude</literal></seg>

	      <seg>
		A file that will be fcntl-locked to ensure that at
		most one &aptitude; process can modify the cache at
		once.  In normal circumstances, you should never need
		to modify this; it may be useful for debugging.
		<emphasis>Note</emphasis>: if &aptitude; complains
		that it cannot acquire a lock, this is
		<emphasis>not</emphasis> because the lock file needs
		to be deleted.  fcntl locks are managed by the kernel
		and will be destroyed when the program holding them
		terminates; failure to acquire the lock means that
		another running program is using it!
	      </seg>
	    </seglistitem>

	    <seglistitem id='configLog'>
	      <seg><literal>Aptitude::Log</literal></seg>

	      <seg><filename>/var/log/aptitude</filename></seg>

	      <seg>
		If this is set to a nonempty string, &aptitude; will
		log the package installations, removals, and upgrades
		that it performs.  If the value of
		<literal>Aptitude::Log</literal> begins with a pipe
		character (ie, <quote><literal>|</literal></quote>),
		the remainder of its value is used as the name of a
		command into which the log will be piped: for
		instance, <literal>|mail -s 'Aptitude install run'
		root</literal> will cause the log to be emailed to
		&root;.  To log to multiple files or commands, you may
		set this option to a list of log targets.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configLoggingFile'>
	      <seg><literal>Aptitude::Logging::File</literal></seg>
	      <seg><filename></filename></seg>

	      <seg>
		If this is set to a nonempty string, &aptitude; will
		write logging messages to it; setting it to
		<quote><literal>-</literal></quote> causes logging
		messages to be printed to standard output.  This
		differs from the setting <link
		linkend='configLog'><literal>Aptitude::Log</literal></link>:
		that file is used to log installations and removals,
		whereas this file is used to log program events,
		errors, and debugging messages (if enabled).  This
		option is equivalent to the command-line argument
		<link
		linkend='cmdlineOptionLogFile'><literal>--log-file</literal></link>.
		See also <link
		linkend='configLoggingLevels'><literal>Aptitude::Logging::Levels</literal></link>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configLoggingLevels'>
	      <seg><literal>Aptitude::Logging::Levels</literal></seg>
	      <seg>(empty)</seg>
	      <seg>
		This option is a group whose members control which log
		messages are written.  Each entry is either
		<quote><replaceable>level</replaceable></quote>, to
		set the global log level (the log level of the root
		logger) to the given <replaceable>level</replaceable>,
		or
		<quote><literal><replaceable>category</replaceable>:<replaceable>level</replaceable></literal></quote>,
		where <replaceable>category</replaceable> is the
		category of messages to modify (such as
		<literal>aptitude.resolver.hints.match</literal>) and
		<replaceable>level</replaceable> is the lowest log
		level of messages in that category that should be
		displayed.  Valid log levels are
		<quote><literal>fatal</literal></quote>,
		<quote><literal>error</literal></quote>,
		<quote><literal>warn</literal></quote>,
		<quote><literal>info</literal></quote>,
		<quote><literal>debug</literal></quote>, and
		<quote><literal>trace</literal></quote>.  The
		command-line option <link
		linkend='cmdlineOptionLogLevel'><literal>--log-level</literal></link>
		can be used to set or override any log level.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configParseDescriptionBullets'>
	      <seg><literal>Aptitude::Parse-Description-Bullets</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is enabled, &aptitude; will attempt
		to automatically detect bulleted lists in package
		descriptions. <!-- TODO: add an appendix describing
		the grammar? -->  This will generally improve how
		descriptions are displayed, but it is not entirely
		backwards-compatible; some descriptions might be
		formatted less attractively when this option is
		<literal>true</literal> than when it is
		<literal>false</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPkg-Display-Limit'>
	      <seg><literal>Aptitude::Pkg-Display-Limit</literal></seg>

	      <seg></seg>

	      <seg>
		The default filter applied to the package list;
		see <xref linkend='secSearchPatterns'/> for
		details about its format.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Allow-Break-Holds'>
	      <seg><literal>Aptitude::ProblemResolver::Allow-Break-Holds</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is set to <literal>true</literal>, the
		problem resolver will consider breaking package holds
		or installing forbidden versions in order to resolve a
		dependency.  If it is set to <literal>false</literal>,
		these actions will be rejected by default, although
		you can always enable them manually (see <xref
		linkend='secResolver'/>).
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-BreakHoldScore'>
	      <seg><literal>Aptitude::ProblemResolver::BreakHoldScore</literal></seg>
	      <seg><literal>-300</literal></seg>
	      <seg>
		How much to reward or penalize solutions that change
		the state of a held package or install a forbidden
		version.  Note that unless <link
		linkend='configProblemResolver-Allow-Break-Holds'><literal>Aptitude::ProblemResolver::Allow-Break-Holds</literal></link>
		is set to true, the resolver will never break a hold
		or install a forbidden version unless it has explicit
		permission from the user.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Break-Hold-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Break-Hold-Level</literal></seg>
	      <seg><literal>50000</literal></seg>
	      <seg>
		The safety cost assigned to actions that break a hold
		set by the user (by upgrading a held package or by
		installing a forbidden version of a package).  See
		<xref linkend='secDependencyResolutionCostsSafetyCosts'/>
		for a description of safety costs.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-BrokenScore'>
	      <seg><literal>Aptitude::ProblemResolver::BrokenScore</literal></seg>
	      <seg><literal>-100</literal></seg>
	      <seg>
		How much to reward or penalize prospective solutions
		based on the number of dependencies they break.  For
		each dependency broken by a possible solution, this
		many points are added to its score; typically this
		should be a negative value.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-DefaultResolutionScore'>
	      <seg><literal>Aptitude::ProblemResolver::DefaultResolutionScore</literal></seg>
	      <seg><literal>400</literal></seg>
	      <seg>
		How much to reward or penalize prospective solutions
		based on how many <quote>default</quote> resolutions
		for currently unsatisfied dependencies they install.
		The default resolution is the resolution that
		<quote><literal>apt-get install</literal></quote> or
		the <quote><link
		linkend='secImmediateResolution'>immediate dependency
		resolver</link></quote> would pick.  The score is only
		applied for dependencies and recommendations whose
		targets are not currently installed.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-DiscardNullSolution'>
	      <seg><literal>Aptitude::ProblemResolver::Discard-Null-Solution</literal></seg>
	      <seg><literal>true</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will never suggest cancelling all of your proposed
		actions in order to resolve a dependency problem.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-EssentialRemoveScore'>
	      <seg><literal>Aptitude::ProblemResolver::EssentialRemoveScore</literal></seg>
	      <seg><literal>-100000</literal></seg>
	      <seg>
		How much to reward or penalize solutions that remove
		an Essential package.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Remove-Essential-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Remove-Essential-Level</literal></seg>
	      <seg><literal>60000</literal></seg>
	      <seg>
		The safety cost assigned to actions that remove an
		Essential package.  See <xref
		linkend='secDependencyResolutionCostsSafetyCosts'/> for a
		description of safety costs.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-ExtraScore'>
	      <seg><literal>Aptitude::ProblemResolver::ExtraScore</literal></seg>
	      <seg><literal>-1</literal></seg>

	      <seg>
		Any version of a package whose Priority is
		<quote>extra</quote> will have this many points added
		to its score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-FullReplacementScore'>
	      <seg><literal>Aptitude::ProblemResolver::FullReplacementScore</literal></seg>
	      <seg><literal>500</literal></seg>

	      <seg>
		Removing a package and installing another package that
		fully replaces it (i.e., conflicts with it, replaces
		it, and provides it) is assigned this score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-FutureHorizon'>
	      <seg><literal>Aptitude::ProblemResolver::FutureHorizon</literal></seg>
	      <seg><literal>50</literal></seg>

	      <seg>
		How many <quote>steps</quote> the resolver should run
		after finding the first solution.  Although &aptitude;
		attempts to generate better solutions before worse
		solutions, sometimes it is unable to do so; this
		setting causes the resolver to briefly continue
		searching for a better solution before displaying its
		results, rather than stopping immediately after it
		finds the first solution.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Hints'>
	      <seg><literal>Aptitude::ProblemResolver::Hints</literal></seg>
	      <seg>(empty)</seg>
	      <seg>
		This option is a group whose members are used to
		configure the problem resolver.  Each item in the
		group is a string describing an action that should be
		applied to one or more packages.  The syntax for each
		hint, and the effect that hints have, may be found in
		<xref linkend='secDependencyResolutionHints'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-ImportantScore'>
	      <seg><literal>Aptitude::ProblemResolver::ImportantScore</literal></seg>
	      <seg><literal>5</literal></seg>

	      <seg>
		Any version of a package whose Priority is
		<quote>important</quote> will have this many points
		added to its score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Infinity'>
	      <seg><literal>Aptitude::ProblemResolver::Infinity</literal></seg>
	      <seg><literal>1000000</literal></seg>

	      <seg>
		A <quote>maximum</quote> score for potential
		solutions.  If a set of actions has a score worse than
		<replaceable>-Infinity</replaceable>, it will be
		discarded immediately.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-InstallScore'>
	      <seg><literal>Aptitude::ProblemResolver::InstallScore</literal></seg>
	      <seg><literal>-20</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		installing a package, if the package is not already
		going to be installed.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Keep-All-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Keep-All-Level</literal></seg>
	      <seg><literal>20000</literal></seg>
	      <seg>
		The safety cost assigned to the single solution that
		cancels all of the actions selected by the user.  See
		<xref linkend='secDependencyResolutionCostsSafetyCosts'/>
		for a description of safety costs.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-KeepScore'>
	      <seg><literal>Aptitude::ProblemResolver::KeepScore</literal></seg>
	      <seg><literal>0</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		keeping a package in its current state, if that
		package is not already going to be kept in its current
		state.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-NonDefaultScore'>
	      <seg><literal>Aptitude::ProblemResolver::NonDefaultScore</literal></seg>
	      <seg><literal>-40</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		installing a non-default version of the package (one
		that is not the current version and not the
		<quote>candidate version</quote>).
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Non-Default-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Non-Default-Level</literal></seg>
	      <seg><literal>50000</literal></seg>
	      <seg>
		The safety cost assigned to actions that install
		non-default versions of a package.  For instance, if
		version 5 of a package is installed, versions 6, 7,
		and 8 are available, and version 7 is the default
		version, then versions 6 and 8 will be given a safety
		cost that is at least this high.  See <xref
		linkend='secDependencyResolutionCostsSafetyCosts'/> for a
		description of safety costs.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-OptionalScore'>
	      <seg><literal>Aptitude::ProblemResolver::OptionalScore</literal></seg>
	      <seg><literal>1</literal></seg>

	      <seg>
		Any version of a package whose Priority is
		<quote>optional</quote> will have this many points
		added to its score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-PreserveAutoScore'>
	      <seg><literal>Aptitude::ProblemResolver::PreserveAutoScore</literal></seg>
	      <seg><literal>0</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		preserving automatic installations or removals.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-PreserveManualScore'>
	      <seg><literal>Aptitude::ProblemResolver::PreserveManualScore</literal></seg>
	      <seg><literal>60</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		preserving explicit user selections.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-RemoveScore'>
	      <seg><literal>Aptitude::ProblemResolver::RemoveScore</literal></seg>
	      <seg><literal>-300</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		removing a package (if it is not already marked for
		removal).
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Remove-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Remove-Level</literal></seg>
	      <seg><literal>10000</literal></seg>
	      <seg>
		The safety cost assigned to actions that remove a
		package.  See <xref
		linkend='secDependencyResolutionCostsSafetyCosts'/> for a
		description of safety costs.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-RequiredScore'>
	      <seg><literal>Aptitude::ProblemResolver::RequiredScore</literal></seg>
	      <seg><literal>4</literal></seg>

	      <seg>
		Any version of a package whose Priority is
		<quote>required</quote> will have this many points
		added to its score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-ResolutionScore'>
	      <seg><literal>Aptitude::ProblemResolver::ResolutionScore</literal></seg>
	      <seg><literal>50</literal></seg>

	      <seg>
		In addition to all other scoring factors, proposed
		solutions that actually resolve all unsatisfied
		dependencies are awarded this many extra points.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Safe-Level'>
	      <seg><literal>Aptitude::ProblemResolver::Safe-Level</literal></seg>
	      <seg><literal>10000</literal></seg>
	      <seg>
		The safety cost assigned to actions that install the
		default version of a package, upgrade a package to its
		default version, or cancel installing or upgrading a
		package.  Solutions assigned this cost could be
		generated by <link
		linkend='manpageSafeUpgrade'><literal>aptitude
		safe-upgrade</literal></link>.  See <xref
		linkend='secDependencyResolutionCostsSafetyCosts'/> for
		a description of safety costs.
	      </seg>
	    </seglistitem>

            <seglistitem id='configProblemResolver-SolutionCost'>
              <seg><literal>Aptitude::ProblemResolver::SolutionCost</literal></seg>
              <seg><literal>safety,priority</literal></seg>

              <seg>
                Describes how to determine the cost of a solution.
                See <xref linkend='secDependencyResolutionCosts'/> for
                a description of what solution costs are, what they
                do, and the syntax used to specify them.  If the cost
                cannot be parsed, an error is issued and the default
                cost is used instead.
              </seg>
            </seglistitem>

	    <seglistitem id='configProblemResolver-StandardScore'>
	      <seg><literal>Aptitude::ProblemResolver::StandardScore</literal></seg>
	      <seg><literal>3</literal></seg>

	      <seg>
		Any version of a package whose Priority is
		<quote>standard</quote> will have this many points
		added to its score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-StepLimit'>
	      <seg><literal>Aptitude::ProblemResolver::StepLimit</literal></seg>
	      <seg><literal>5000</literal></seg>
	      <seg>
		The maximum number of <quote>steps</quote> which
		should be performed by the problem resolver on each
		attempt to find a solution to a dependency problem.
		Decreasing this number will make &aptitude;
		<quote>give up</quote> sooner; increasing it will
		permit the search for a solution to consume much more
		time and memory before it is aborted.  Setting
		<literal>StepLimit</literal> to 0 will disable the
		problem resolver entirely.  The default value is large
		enough to accomodate commonly encountered situations,
		while preventing &aptitude; from <quote>blowing
		up</quote> if an overly complicated problem is
		encountered.  (note: this applies only to command-line
		searches; in the visual interface, the resolver will
		continue working until it reaches a solution)
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-StepScore'>
	      <seg><literal>Aptitude::ProblemResolver::StepScore</literal></seg>
	      <seg><literal>70</literal></seg>

	      <seg>
		How much to reward or penalize prospective solutions
		based on their length.  For each action performed by a
		solution, this many points are added to its score.
		The larger this value is, the more the resolver tends
		to stick with its first choice rather than considering
		alternatives; this will cause it to produce a solution
		more quickly, but the solution might be of slightly
		lower quality than it would otherwise be.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Trace-Directory'>
	      <seg><literal>Aptitude::ProblemResolver::Trace-Directory</literal></seg>
	      <seg></seg>
	      <seg>
		If this value is set, then each time the problem
		resolver produces a solution, a stripped-down version
		of the package state sufficient to reproduce that
		solution is written to the given file.  If
		<literal>Aptitude::ProblemResolver::Trace-File</literal>
		is also set, the same information will also be written
		to the trace file.  Trace directories are more
		transparent than trace files, and are more suitable
		for, e.g., including in source trees as test cases.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-Trace-File'>
	      <seg><literal>Aptitude::ProblemResolver::Trace-File</literal></seg>
	      <seg></seg>
	      <seg>
		If this value is set, then each time the problem
		resolver produces a solution, a stripped-down version
		of the package state sufficient to reproduce that
		solution is written to the given file.  If
		<literal>Aptitude::ProblemResolver::Trace-Directory</literal>
		is also set, the same information will also be written
		to the trace directory.  A trace file is simply a
		compressed archive of a trace directory; it will take
		less space than the trace directory and is suitable
		for transmission over a network.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-UndoFullReplacementScore'>
	      <seg><literal>Aptitude::ProblemResolver::UndoFullReplacementScore</literal></seg>
	      <seg><literal>-500</literal></seg>
	      <seg>
		Installing a package and removing another package that
		fully replaces it (i.e., conflicts with it, replaces
		it, and provides it) is assigned this score.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-UnfixedSoftScore'>
	      <seg><literal>Aptitude::ProblemResolver::UnfixedSoftScore</literal></seg>
	      <seg><literal>-200</literal></seg>
	      <seg>
		How much to reward or penalize leaving a Recommends
		relationship unresolved.  This should typically be
		less than RemoveScore, or &aptitude; will tend to
		remove packages rather than leaving their
		Recommendations unfixed.  See <xref
		linkend='secResolver'/> for details.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configProblemResolver-UpgradeScore'>
	      <seg><literal>Aptitude::ProblemResolver::UpgradeScore</literal></seg>
	      <seg><literal>0</literal></seg>
	      <seg>
		How much weight the problem resolver should give to
		upgrading (or downgrading) a package to its candidate
		version, if the package was not already going to be
		upgraded.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPurge-Unused'>
	      <seg><literal>Aptitude::Purge-Unused</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal> and
		<literal><link
		linkend='configDelete-Unused'>Aptitude::Delete-Unused</link></literal>
		is also <literal>true</literal>, then packages which
		are unused will be <emphasis>purged</emphasis> from
		the system, removing their configuration files and
		perhaps other important data.  For more information
		about which packages are considered to be
		<quote>unused</quote>, see <xref
		linkend='secAutoInstall'/>.  <emphasis>THIS OPTION CAN
		CAUSE DATA LOSS!  DO NOT ENABLE IT UNLESS YOU KNOW
		WHAT YOU ARE DOING!</emphasis>
	      </seg>
	    </seglistitem>

	    <seglistitem id='configRecommends-Important'>
	      <seg><literal>Aptitude::Recommends-Important</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		This is an obsolete configuration option that has been
		superseded by <link
		linkend='configAptInstall-Recommends'><literal>Apt::Install-Recommends</literal></link>.
		On startup, &aptitude; will copy
		<literal>Aptitude::Recommends-Important</literal> (if
		it exists) to
		<literal>Apt::Install-Recommends</literal> and then
		clear
		<literal>Aptitude::Recommends-Important</literal> in
		your user configuration file.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configSafe-Resolver-No-New-Installs'>
	      <seg><literal>Aptitude::Safe-Resolver::No-New-Installs</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is <literal>true</literal>, then when
		the <quote>safe</quote> dependency resolver has been
		activated via <link
		linkend='cmdlineSafeResolver'><literal>--safe-resolver</literal></link>
		or by using the <link
		linkend='manpageSafeUpgrade'><literal>safe-upgrade</literal></link>
		command-line action, the resolver will not be allowed
		to install packages that are not currently installed.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configSafe-Resolver-No-New-Upgrades'>
	      <seg><literal>Aptitude::Safe-Resolver::No-New-Upgrades</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		If this option is enabled, then when the
		<quote>safe</quote> dependency resolver has been
		activated via <link
		linkend='cmdlineSafeResolver'><literal>--safe-resolver</literal></link>
		or by using the <link
		linkend='manpageSafeUpgrade'><literal>safe-upgrade</literal></link>
		command-line action, the resolver will not be allowed
		to resolve dependencies by upgrading packages.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDescriptions'>
	      <seg><literal>Aptitude::Sections::Descriptions</literal></seg>
	      <seg>See <literal>$prefix/share/aptitude/section-descriptions</literal></seg>
	      <seg>
		This option is a group whose members define the
		descriptions displayed for each section when using the
		<quote><literal>section</literal></quote> package
		hierarchy grouping policy.  Descriptions are assigned
		to section trees based on the last component of the
		name: for instance, a member of this group named
		<quote><literal>games</literal></quote> will be used
		to describe the Sections
		<quote><literal>games</literal></quote>,
		<quote><literal>non-free/games</literal></quote>, and
		<quote><literal>non-free/desktop/games</literal></quote>.
		Within the text of section descriptions, the string
		<quote><literal>\n</literal></quote> will be replaced
		by a line-break, and the string
		<quote><literal>''</literal></quote> will be replaced
		by a double-quote character.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configTop-Sections'>
	      <seg><literal>Aptitude::Sections::Top-Sections</literal></seg>
	      <seg><literal>"main"; "contrib"; "non-free"; "non-US";</literal></seg>
	      <seg>
		A configuration group whose elements are the names of
		the top-level archive sections.  The
		<quote><literal>topdir</literal></quote>,
		<quote><literal>subdir</literal></quote>, and
		<quote><literal>subdirs</literal></quote> grouping
		policies use this list to interpret Section fields: if
		the first path element of a package's Section is
		<emphasis>not</emphasis> contained in this list, or if
		its Section has only one element, then the package
		will be grouped using the first member of this list as
		its first path element.  For example, if the first
		member of <literal>Top-Sections</literal> is
		<quote><literal>main</literal></quote>, then a package
		whose Section is
		<quote><literal>games/arcade</literal></quote> will be
		treated as if its Section field were
		<quote><literal>main/games/arcade</literal></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configSimulate'>
	      <seg><literal>Aptitude::Simulate</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, causes &aptitude; to just
		display the actions that would be performed (rather
		than actually performing them); in the visual
		interface, causes &aptitude; to start in read-only
		mode regardless of whether you are &root; or not.
		This is equivalent to the <literal>-s</literal>
		command-line option.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configSpin-Interval'>
	      <seg><literal>Aptitude::Spin-Interval</literal></seg>

	      <seg><literal>500</literal></seg>

	      <seg>
		The number of milliseconds to delay in between
		updating the <quote>spinner</quote> that appears while
		the problem resolver is running.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configSuggests-Important'>
	      <seg><literal>Aptitude::Suggests-Important</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		This is an obsolete option; use <literal><link
		linkend='configApt-AutoRemove-SuggestsImportant'>Apt::AutoRemove::Suggests-Important</link></literal>
		instead.  Setting this option to
		<literal>true</literal> has the same effect as setting
		<literal><link
		linkend='configApt-AutoRemove-SuggestsImportant'>Apt::AutoRemove::Suggests-Important</link></literal>
		to <literal>true</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='suppressReadOnlyWarning'>
	      <seg><literal>Aptitude::Suppress-Read-Only-Warning</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>false</literal>, &aptitude;
		will display a warning the first time that you attempt
		to modify package states while &aptitude; is in
		read-only mode.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configTheme'>
	      <seg><literal>Aptitude::Theme</literal></seg>

	      <seg></seg>

	      <seg>
		The theme that &aptitude; should use; see <xref
		linkend='secThemes'/> for more information.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configTrack-Dselect-State'>
	      <seg><literal>Aptitude::Track-Dselect-State</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is set to
		<literal>true</literal>, &aptitude; will attempt
		to detect when a change to a package's state has
		been made using &dselect; or
		<command>dpkg</command>: for instance, if you
		remove a package using <command>dpkg</command>,
		&aptitude; will not try to reinstall it.  Note
		that this may be somewhat buggy.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAdvance-On-Action'>
	      <seg><literal>Aptitude::UI::Advance-On-Action</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is set to
		<literal>true</literal>, changing a package's
		state (for instance, marking it for
		installation) will cause &aptitude; to advance
		the highlight to the next package in the current
		group.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configAuto-Show-Reasons'>
	      <seg><literal>Aptitude::UI::Auto-Show-Reasons</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is set to
		<literal>true</literal>, selecting a package
		which is broken or which appears to be causing
		other packages to be broken will cause the
		information area to automatically display some
		reasons why the breakage might be occuring.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDefault-Grouping'>
	      <seg><literal>Aptitude::UI::Default-Grouping</literal></seg>

	      <seg><literal>filter(missing),status,section(subdirs,passthrough),section(topdir)</literal></seg>

	      <seg>
		Sets the default grouping policy used for
		package lists.  See <xref
		linkend='secGroupingPolicy'/> for additional
		information on grouping policies.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDefault-Package-View'>
	      <seg><literal>Aptitude::UI::Default-Package-View</literal></seg>

	      <seg></seg>

	      <seg>
		This option is a group whose members define the
		default layout of &aptitude;'s display.  See
		<xref linkend='secDisplayLayout'/> for more
		information.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDefault-Preview-Grouping'>
	      <seg><literal>Aptitude::UI::Default-Preview-Grouping</literal></seg>

	      <seg><literal>action</literal></seg>

	      <seg>
		Sets the default grouping policy used for
		preview screens.  See <xref
		linkend='secGroupingPolicy'/> for additional
		information on grouping policies.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDefault-Sorting'>
	      <seg><literal>Aptitude::UI::Default-Sorting</literal></seg>
	      <seg><literal>name</literal></seg>

	      <seg>
		The default sorting policy of package views.  See
		<xref linkend='secSortingPolicy'/> for more
		information.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDescription-Visible-By-Default'>
	      <seg><literal>Aptitude::UI::Description-Visible-By-Default</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		When a package list is first displayed, the
		information area (which typically contains the
		long description of the current package) will be
		visible if this option is
		<literal>true</literal> and hidden if it is
		<literal>false</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configExit-On-Last-Close'>
	      <seg><literal>Aptitude::UI::Exit-On-Last-Close</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		closing all the active views will quit
		&aptitude;; otherwise, &aptitude; will not exit
		until you issue the command &actions-quit;.  See
		<xref linkend='secViews'/> for more information.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configFill-Text'>
	      <seg><literal>Aptitude::UI::Fill-Text</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will format descriptions so that each
		line is exactly the width of the screen.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configFlat-View-As-First-View'>
	      <seg><literal>Aptitude::UI::Flat-View-As-First-View</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will display a flat view on startup
		instead of the default view.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configHelpBar'>
	      <seg><literal>Aptitude::UI::HelpBar</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, a
		line of information about important keystrokes
		will be displayed at the top of the screen.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configIncremental-Search'>
	      <seg><literal>Aptitude::UI::Incremental-Search</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will perform
		<quote>incremental</quote> searches: as you type
		the search pattern, it will search for the next
		package matching what you have typed so far.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configUIInfoAreaTabs'>
	      <seg><literal>Aptitude::UI::InfoAreaTabs</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will display tabs at the top of the information area
		(the pane at the bottom of the screen) describing the
		different modes the area can be set to.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configKeybindings'>
	      <seg><literal>Aptitude::UI::Keybindings</literal></seg>

	      <seg></seg>

	      <seg>
		This is a group whose members define the
		connections between keystrokes and commands in
		&aptitude;.  For more information, see <xref
		linkend='secKeybindings'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configMenubar-Autohide'>
	      <seg><literal>Aptitude::UI::Menubar-Autohide</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is set to
		<literal>true</literal>, the menu bar will be
		hidden while it is not in use.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configMinibuf-Download-Bar'>
	      <seg><literal>Aptitude::UI::Minibuf-Download-Bar</literal></seg>
	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is set to
		<literal>true</literal>, &aptitude; will use a
		less obtrusive mechanism to display the progress
		of downloads: a bar at the bottom of the screen
		will appear which displays the current download
		status.  While the download is active, pressing
		<keycap>q</keycap> will abort it.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configMinibuf-Prompts'>
	      <seg><literal>Aptitude::UI::Minibuf-Prompts</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, some
		prompts (such as yes/no and multiple-choice
		prompts) will be displayed at the bottom of the
		screen instead of in dialog boxes.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configNew-Package-Commands'>
	      <seg><literal>Aptitude::UI::New-Package-Commands</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is set to
		<literal>false</literal>, commands such as
		&package-install; will have the same deprecated
		behavior that they did in antique versions of
		&aptitude;.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPackage-Display-Format'>
	      <seg><literal>Aptitude::UI::Package-Display-Format</literal></seg>

	      <seg><literal>%c%a%M %p %Z %v %V</literal></seg>

	      <seg>
		This option controls the format string used to
		display packages in package lists.  For more
		information on format strings, see <xref
		linkend='secDisplayFormat'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPackage-Header-Format'>
	      <seg><literal>Aptitude::UI::Package-Header-Format</literal></seg>

	      <seg><literal>%N %n #%B %u %o</literal></seg>

	      <seg>
		This option controls the format string used to
		display the header line of package lists (ie,
		the line that appears between the package list
		and the menu bar).  For more
		information on format strings, see <xref
		linkend='secDisplayFormat'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPackage-Status-Format'>
	      <seg><literal>Aptitude::UI::Package-Status-Format</literal></seg>

	      <seg><literal>%d</literal></seg>

	      <seg>
		This option controls the format string used to
		display the status line of package lists (ie,
		the line that appears between the package list
		and the information area).  For more
		information on format strings, see <xref
		linkend='secDisplayFormat'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPause-After-Download'>
	      <seg><literal>Aptitude::UI::Pause-After-Download</literal></seg>

	      <seg><literal>OnlyIfError</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will display a message after it finishes downloading
		packages, asking you if you want to continue with the
		installation.  If it is
		<literal>OnlyIfError</literal>, a message will only be
		displayed if a download failed.  Otherwise, if the
		option is set to <literal>false</literal>, &aptitude;
		will immediately proceed to the next screen after
		completing a download.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPreview-Limit'>
	      <seg><literal>Aptitude::UI::Preview-Limit</literal></seg>

	      <seg></seg>

	      <seg>
		The default filter applied to the preview screen;
		see <xref linkend='secSearchPatterns'/> for
		details about its format.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configPrompt-On-Exit'>
	      <seg><literal>Aptitude::UI::Prompt-On-Exit</literal></seg>
	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will display a confirmation prompt
		before shutting down.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configColors'>
	      <seg><literal>Aptitude::UI::Styles</literal></seg>

	      <seg></seg>

	      <seg>
		This is a configuration group whose contents define
		what textual styles &aptitude; uses to display
		information.  For more information, see <xref
		linkend='secStyle'/>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='viewTabs'>
	      <seg><literal>Aptitude::UI::ViewTabs</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is set to <literal>false</literal>,
		&aptitude; will not display <quote>tabs</quote>
		describing the currently active views at the top of
		the screen.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configWarn-Not-Root'>
	      <seg><literal>Aptitude::Warn-Not-Root</literal></seg>

	      <seg><literal>true</literal></seg>

	      <seg>
		If this option is <literal>true</literal>,
		&aptitude; will detect when you need &root;
		privileges to do something, and ask you whether
		you want to switch to the &root; account if you
		aren't &root; already.  See <xref
		linkend='secBecomingRoot'/> for more
		information.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDebTags-Vocabulary'>
	      <seg><literal>DebTags::Vocabulary</literal></seg>
	      <seg><literal>/usr/share/debtags/vocabulary</literal></seg>
	      <seg>
		The location of the <literal>debtags</literal>
		vocabulary file; used to load in the package tag
		metadata.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configDir-Aptitude-State'>
	      <seg><literal>Dir::Aptitude::state</literal></seg>
	      <seg><filename>/var/lib/aptitude</filename></seg>
	      <seg>
		The directory in which &aptitude;'s persistent
		state information is stored.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configQuiet'>
	      <seg><literal>Quiet</literal></seg>

	      <seg><literal>0</literal></seg>

	      <seg>
		This controls the quietness of the command-line mode.
		Setting it to a higher value will disable more
		progress indicators.
	      </seg>
	    </seglistitem>
	  </segmentedlist>
	</section>
      </section>

      <section id='secThemes'>
	<title>Themes</title>

	<para>
	  A <firstterm>theme</firstterm> in &aptitude; is simply a
	  collection of settings that <quote>go together</quote>.
	  Themes work by overriding the default values of options: if
	  an option is not set in the system configuration file or in
	  your personal configuration file, &aptitude; will use the
	  setting from the current theme, if one is available, before
	  using the standard default value.
	</para>

	<para>
	  A theme is simply a named group under
	  <literal>Aptitude::Themes</literal>; each configuration
	  option contained in the group will override the
	  corresponding option in the global configuration.  For
	  instance, if the <literal>Dselect</literal> theme is
	  selected, the option
	  <literal>Aptitude::Themes::Dselect::Aptitude::UI::Package-Display-Format</literal>
	  will override the default value of the option
	  <literal>Aptitude::UI::Package-Display-Format</literal>.
	</para>

	<para>
	  To select a theme, set the configuration option <literal>Aptitude::Theme</literal> to the name of the theme; for instance,
	</para>

	<screen>Aptitude::Theme Vertical-Split;</screen>

	<para>
	  The following themes are shipped with &aptitude; in
	  <filename>/usr/share/aptitude/aptitude-defaults</filename>:
	</para>

	<variablelist>
	  <varlistentry>
	    <term><literal>Dselect</literal></term>

	    <listitem>
	      <para>
		This theme makes &aptitude; look and behave more like
		the legacy <literal>dselect</literal> package manager:
	      </para>

	      <screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref='images/dselect-theme.png' format='PNG' width='100%' scalefit='1'/>
		  </imageobject>

		  <textobject role='text'>
		    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
--\ Installed Packages
  --\ Priority required
    --\ base - The Debian base system
c   base  base-file 3.0.16      3.0.16      Debian base system miscellaneous fil
c   base  base-pass 3.5.7       3.5.7       Debian base system master password a
c   base  bash      2.05b-15    2.05b-15    The GNU Bourne Again SHell
c   base  bsdutils  1:2.12-7    1:2.12-7    Basic utilities from 4.4BSD-Lite
c   base  coreutils 5.0.91-2    5.0.91-2    The GNU core utilities
c   base  debianuti 2.8.3       2.8.3       Miscellaneous utilities specific to
c   base  diff      2.8.1-6     2.8.1-6     File comparison utilities
base-files                      installed ; none                       required
This package contains the basic filesystem hierarchy of a Debian system, and
several important miscellaneous files, such as /etc/debian_version,
/etc/host.conf, /etc/issue, /etc/motd, /etc/profile, /etc/nsswitch.conf, and
others, and the text of several common licenses in use on Debian systems.






</screen>
		  </textobject>
		</mediaobject>
	      </screenshot>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>Vertical-Split</literal></term>

	    <listitem>
	      <para>
		This theme rearranges the display: instead of the
		current package's description appearing underneath the
		package list, it is displayed to the right of the
		package list.  This theme is useful with very wide
		terminals, and perhaps also when editing the built-in
		hierarchy of packages.
	      </para>

	      <screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref='images/vertical-split-theme.png' format='PNG' width='100%' scalefit='1'/>
		  </imageobject>

		  <textobject role='text'>
		    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
aptitude 0.2.14.1
--\ Installed Packages                  Modern computers support the Advanced  #
  --\ admin - Administrative utilities  Configuration and Power Interface
    --\ main - The main Debian archive  (ACPI) to allow intelligent power
i   acpid         1.0.3-19   1.0.3-19   management on your system and to query
i   alien         8.44       8.44       battery and configuration status.
i   anacron       2.3-9      2.3-9
i   apt-show-vers 0.07       0.07       ACPID is a completely flexible, totally
i A apt-utils     0.5.25     0.5.25     extensible daemon for delivering ACPI
i   apt-watch     0.3.2-2    0.3.2-2    events. It listens on a file
i   aptitude      0.2.14.1-2 0.2.14.1-2 (/proc/acpi/event) and when an event
i   at            3.1.8-11   3.1.8-11   occurs, executes programs to handle the
i   auto-apt      0.3.20     0.3.20     event. The programs it executes are
i   cron          3.0pl1-83  3.0pl1-83  configured through a set of
i   debconf       1.4.29     1.4.29     configuration files, which can be
i   debconf-i18n  1.4.29     1.4.29     dropped into place by packages or by
i A debootstrap   0.2.39     0.2.39     the admin.
i A deborphan     1.7.3      1.7.3
i   debtags       0.16       0.16       In order to use this package you need a
i A defoma        0.11.8     0.11.8     recent Kernel (=>2.4.7). This can be
i   discover      2.0.4-5    2.0.4-5    one including the patches on
Utilities for using ACPI power management</screen>
		  </textobject>
		</mediaobject>
	      </screenshot>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </section>

    </section>

    <section id='secMinesweeper'>
      <title>Playing Minesweeper</title>

      <para>
	In case you get tired of installing and removing packages,
	&aptitude; includes a version of the classic game
	<quote>Minesweeper</quote>.  To start it, select
	&actions-mine;; the initial Minesweeper board will appear:
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref='images/mine-snapshot.png' format='PNG' width='100%' scalefit='1'/>
	  </imageobject>

	  <textobject role='text'>
	    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
Minesweeper                                              10/10 mines  13 seconds





                                   +--------+
                                   |        |
                                   |        |
                                   |        |
                                   |        |
                                   |        |
                                   |        |
                                   |        |
                                   |        |
                                   +--------+





</screen>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	Within the rectangle that appears on the screen are hidden ten
	mines.  Your goal is to determine, through intuition, logic,
	and luck, where those mines are, without setting any of them
	off!  To do this, you must uncover all the squares that
	<emphasis>do not</emphasis> contain mines; in doing so, you
	will learn important information regarding which squares do
	contain mines.  Beware, however: uncovering a square that
	contains a mine will set it off, ending your game immediately!
      </para>

      <para>
	To uncover a square (and find out whether a mine is hidden
	there), select the square with the arrow keys and press
	<keycap>Enter</keycap>:
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref='images/mine-snapshot2.png' format='PNG' width='100%' scalefit='1'/>
	  </imageobject>

	  <textobject role='text'>
	    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
Minesweeper                                             10/10 mines  387 seconds





                                   +--------+
                                   | 2......|
                                   | 2111...|
                                   |    1...|
                                   | 1111...|
                                   |11...111|
                                   |...113  |
                                   |1122    |
                                   |        |
                                   +--------+





</screen>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	As you can see, some of the hidden (blank) parts of the board
	have been revealed in this screenshot.  The squares containing
	a <literal>.</literal> are squares which are not next to
	any mines; the numbers in the remaining squares indicate how
	many mines they are next to.
      </para>

      <para>
	If you think you know where a mine is, you can place a
	<quote>flag</quote> on it.  To do this, select the suspected
	square and press <keycap>f</keycap>.  For instance, in the
	screenshot below, I decided that the square on the left-hand
	side of the board looked suspicious...
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref='images/mine-snapshot3.png' format='PNG' width='100%' scalefit='1'/>
	  </imageobject>

	  <textobject role='text'>
	    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
Minesweeper                                              9/10 mines  961 seconds





                                   +--------+
                                   | 2......|
                                   | 2111...|
                                   |    1...|
                                   |F1111...|
                                   |11...111|
                                   |...113  |
                                   |1122    |
                                   |        |
                                   +--------+





</screen>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	As you can see, an <literal>F</literal> appeared in the
	selected square.  It is no longer possible to uncover this
	square, even accidentally, until the flag is removed (by
	pressing <keycap>f</keycap> again).  Once you have placed
	flags on all the mines that are next to a square (for
	instance, the squares labelled <literal>1</literal> next to
	the flag above), you can <quote>sweep</quote> around the
	square.  This is just a convenient shortcut to uncover all the
	squares next to it (except those containing a flag, of
	course).  For instance, sweeping around the
	<literal>1</literal> above:
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref='images/mine-snapshot4.png' format='PNG' width='100%' scalefit='1'/>
	  </imageobject>

	  <textobject role='text'>
	    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
Minesweeper                                              9/10 mines  2290 seconds





                                   +--------+
                                   | 2......|
                                   | 2111...|
                                   |221 1...|
                                   |F1111...|
                                   |11...111|
                                   |...113  |
                                   |1122    |
                                   |        |
                                   +--------+





</screen>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	Luckily (or was it luck?), my guess about the location of that
	mine was correct.  If I had been wrong, I would have lost
	immediately:
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref='images/mine-snapshot5.png' format='PNG' width='100%' scalefit='1'/>
	  </imageobject>

	  <textobject role='text'>
	    <screen> Actions  Undo  Package  Search  Options  Views  Help
f10: Menu  ?: Help  q: Quit  u: Update  g: Download/Install/Remove Pkgs
Minesweeper                                   Minesweeper    Lost in 2388 seconds





                                   +--------+
                                   |^2......|
                                   |^2111...|
                                   |221^1...|
                                   |^1111...|
                                   |11...111|
                                   |...113^ |
                                   |1122* ^ |
                                   | ^ ^   ^|
                                   +--------+





</screen>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	When you lose, the locations of all the mines are revealed:
	unexploded mines are indicated by a caret symbol
	(<literal>^</literal>), and the one you <quote>stepped
	on</quote> is indicated by an asterisk (<literal>*</literal>).
      </para>
    </section>
  </chapter>

  <chapter id='chapFAQ'>
    <title>aptitude frequently asked questions</title>

    <blockquote>
      <attribution>
	  <citetitle pubwork='book'>Monty Python and the Holy Grail</citetitle>
      </attribution>

      <para>
	<quote>What ... is your name?</quote>
      </para>

      <para>
	<quote>I am Arthur, King of the Britons.</quote>
      </para>

      <para>
	<quote>What ... is your quest?</quote>
      </para>

      <para>
	<quote>I seek the Holy Grail!</quote>
      </para>

      <para>
	<quote>What ... is the airspeed velocity of an unladen swallow?</quote>
      </para>

      <para>
	<quote>What do you mean?  An African or a European swallow?</quote>
      </para>

      <para>
	<quote>Huh?  I ... I don't kn---<emphasis>AAAAAUUUGGGHH!</emphasis></quote>
      </para>
    </blockquote>

    <qandaset>
      <qandaentry>
	<question>
	  <para>
	    How can I find exactly one package by name?
	  </para>
	</question>

	<answer>
	  <para>
	    As mentioned in <xref linkend='secSearchPatterns'/>, when
	    you search for a package by name, the text you enter is
	    actually a regular expression.  Thus, the search pattern
	    <quote><literal>^<replaceable>name</replaceable>$</literal></quote>
	    will match only a package named
	    <replaceable>name</replaceable>.
	  </para>

	  <para>
	    For instance, you can find <literal>apt</literal> (but not
	    <literal>aptitude</literal> or
	    <literal>synaptic</literal>) by entering
	    <userinput>^apt$</userinput>; you can find
	    <literal>g++</literal> (but not
	    <literal>g++-2.95</literal> or <literal>g++-3.0</literal>)
	    by entering <userinput>^g\+\+$</userinput>.
	  </para>
	</answer>
      </qandaentry>

      <qandaentry>
	<question>
	  <para>
	    How can I find broken packages?
	  </para>
	</question>

	<answer>
	  <para>
	    Use the command &search-find-broken;.
	  </para>
	</answer>
      </qandaentry>

      <qandaentry>
	<question>
	  <para>
	    I want to select text, why doesn't &aptitude; let me disable
	    the mouse?
	  </para>
	</question>

	<answer>
	  <para>
	    Normally, you cannot select text in an xterm while a
	    program running in that terminal (such as &aptitude;) is
	    using the mouse.  However, you can override this behavior
	    and perform a selection by holding the
	    <keycap>Shift</keycap> key down while you click on the
	    terminal.
	  </para>
	</answer>
      </qandaentry>
    </qandaset>
  </chapter>

  <chapter>
    <title>Credits</title>

    <blockquote>
      <attribution>
	<personname>
	  <firstname>Terry</firstname>
	  <surname>Pratchett</surname>
	  </personname>,
	  <citetitle pubwork='book'>The Last Hero</citetitle>
      </attribution>

      <para>
	No-one remembers the singer.
	The song remains.
      </para>
    </blockquote>

    <para>
      This section commemorates some of the people who have
      contributed to &aptitude; over its lifetime.
    </para>

    <note>
      <para>
	This section is presently rather incomplete and will likely be
	updated and expanded as time goes on (in particular, there are
	many missing translation credits due to the huge number of
	sources of translations
	<footnote>
	  <para>
	    It should be possible to compile a fairly complete list of
	    i18n contributors based on the ChangeLog, its references
	    to the Debian bug tracking system, and the revision
	    history of &aptitude;, but doing so will require a large
	    investment of time that is not currently available.
	  </para>
	</footnote>).  If you think you should be on this
	list, please email <email>dburrows@debian.org</email> with an
	explanation of why you think so.
      </para>
    </note>

    <variablelist>
      <title>Translations and internationalization</title>

      <varlistentry>
	<term>Brazilian translation</term>

	<listitem>
	  <para>
	    Andre Luis Lopes, Gustavo Silva
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Chinese translation</term>

	<listitem>
	  <para>
	    Carlos Z.F. Liu
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Czech translation</term>

	<listitem>
	  <para>
	    Miroslav Kure
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Danish translation</term>

	<listitem>
	  <para>
	    Morten Brix Pedersen, Morten Bo Johansen
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Dutch translation</term>

	<listitem>
	  <para>
	    Luk Claes
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Finnish translation</term>

	<listitem>
	  <para>
	    Jaakko Kangasharju
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>French translation</term>

	<listitem>
	  <para>
	    Martin Quinson, Jean-Luc Coulon
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>German translation</term>

	<listitem>
	  <para>Sebastian Schaffert, Erich Schubert, Sebastian Kapfer, Jens Seidel</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Italian translation</term>

	<listitem>
	  <para>
	    Danilo Piazzalunga
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Japanese translation</term>

	<listitem>
	  <para>
	    Yasuo Eto, Noritada Kobayashi
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Lithuanian translation</term>

	<listitem>
	  <para>
	    Darius ?itkevicius
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Polish translation</term>

	<listitem>
	  <para>
	    Michal Politowski
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Portuguese translation</term>

	<listitem>
	  <para>
	    Nuno Sénica, Miguel Figueiredo
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Norwegian translation</term>

	<listitem>
	  <para>
	    Håvard Korsvoll
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Spanish translation</term>

	<listitem>
	  <para>
	    Jordi Malloch, Ruben Porras
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Swedish translation</term>

	<listitem>
	  <para>
	    Daniel Nylander
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Initial i18n patch</term>

	<listitem><para>Masato Taruishi</para></listitem>
      </varlistentry>

      <varlistentry>
	<term>i18n triaging and maintainence</term>

	<listitem><para>Christian Perrier</para></listitem>
      </varlistentry>
    </variablelist>

    <variablelist>
      <title>Documentation</title>

      <varlistentry>
	<term>User's Manual</term>

	<listitem>
	  <para>
	    Daniel Burrows
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <variablelist>
      <title>Programming</title>

      <varlistentry>
	<term>Program design and implementation</term>

	<listitem>
	  <para>
	    Daniel Burrows
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Support for the dpkg Breaks field</term>

	<listitem>
	  <para>
	    Ian Jackson, Michael Vogt
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </chapter>

  <reference id='secReference'>
    <title>Command-line reference</title>

    &manpage;
  </reference>

</book>

<!-- LocalWords:  unversioned
-->