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.4.3'>

  <!-- 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-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 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-ui "<menuchoice><guimenu>Options</guimenu><guimenuitem>UI options</guimenuitem></menuchoice>">
  <!ENTITY options-dep "<menuchoice><guimenu>Options</guimenu><guimenuitem>Dependency handling</guimenuitem></menuchoice>">
  <!ENTITY options-misc "<menuchoice><guimenu>Options</guimenu><guimenuitem>Miscellaneous</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>">


  <!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-2006</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>, 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 from <ulink
		  url='http://libsigc.sourceforge.net'></ulink>.
		</para>
	      </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>
	    </itemizedlist>
	  </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>Getting &aptitude; from darcs</title>

	<para>
	  If you want to test the latest bleeding-edge source code or
	  to otherwise help &aptitude; development, you can download
	  unreleased &aptitude; source code using darcs.  Install
	  darcs (available from <ulink
	  url='http://www.darcs.net'></ulink>) and execute the command
	  <command>darcs get
	  http://people.debian.org/~dburrows/darcs/aptitude</command>
	  to retrieve the most recent source code.  Once the source
	  code is available on your computer, you can
	  <command>cd</command> into it and type <command>darcs
	  pull</command> to update it with any changes made to the
	  main repository.
	</para>

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

	<warning>
	  <para>
	    The &aptitude; darcs 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>
  </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 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</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 <literal>~b</literal>.
	  </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>

	  <screenshot id='solutionScreenSnapshot2'>
	    <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>

	  <!-- 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>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>upgrade</arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      This command will upgrade as many packages as possible.
	      If there are dependency problems, it will avoid
	      upgrading packages (rather than, for instance, removing
	      them).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <cmdsynopsis>
	      <command>aptitude</command>
	      <arg choice='plain'>dist-upgrade</arg>
	    </cmdsynopsis>
	  </term>

	  <listitem>
	    <para>
	      This command will also 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>
	  </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>
	    </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-all
.
.
.
The following actions will resolve these dependencies:

Install the following packages:
libsdl1.2debian-oss [1.2.7+1.2.8cvs20041007-4.1 (unstable)]

Score is 19

<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-alsa [1.2.7+1.2.8cvs20041007-4.1 (unstable,now)]

Score is 19

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

      <para>
	Typing <userinput>q</userinput> will <quote>give up</quote>
	and quit the program immediately:
      </para>

      <screen><prompt>Accept this solution? [Y/n/q/?]</prompt> <userinput>q</userinput>
Abandoning all efforts to resolve these dependencies.
Abort.</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>
	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; UI</title>

      <para>
	This section describes the parts of the 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 the program, 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 the program
		      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-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>
		    <entry>&resolver-reject;</entry>

		    <entry>
		      When examining a solution, toggle whether the
		      currently selected action is rejected and move
		      to the next action (see <xref
		      linkend='secResolver'/>).  If the action is
		      currently approved, its approval will be
		      cancelled.
		    </entry>
		  </row>

		  <row>
		    <entry>&resolver-approve;</entry>

		    <entry>
		      When examining a solution, toggle whether the
		      currently selected action is approved and move
		      to the next action (see <xref
		      linkend='secResolver'/>).  If the action is
		      currently rejected, its rejection will be
		      cancelled.
		    </entry>
		  </row>

		  <row>
		    <entry>&resolver-view-target;</entry>

		    <entry>
		      When examining a solution, view detailed
		      information about the package which is affected
		      by the currently selected action (see <xref
		      linkend='secResolver'/>).
		    </entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  </figure>
	</section>

	<section>
	  <title>The Search Menu</title>

	  <figure>
	    <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>
		    <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
		      <literal>~b</literal>.
		    </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-ui;</entry>

		    <entry>
		      Display a dialog box in which you can set
		      options pertaining to the interface (how
		      messages are displayed, how packages are
		      organized, etc).<!--  TODO: See <xref
		      linkend='secOptionsUI'/>. -->
		    </entry>
		  </row>

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

		    <entry>
		      Display a dialog box in which you can set
		      options pertaining to how dependencies are
		      treated: for instance, whether to automatically
		      install packages which are recommended by other
		      packages.  <!-- TODO: See <xref
		      linkend='secOptionsDep'/>. -->
		    </entry>
		  </row>

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

		    <entry>
		      Display a dialog box in which you can set
		      options that don't fit into the previous two
		      categories: for instance, whether packages
		      should be automatically flagged for upgrade when
		      &aptitude; starts. <!-- TODO:  See <xref
		      linkend='secOptionsMisc'/>. -->
		    </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>
      </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.
		    Futhermore, 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
			<command>dist-upgrade</command> or
			<command>upgrade</command> 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='secResolver'>
	<title>Solving Dependency Problems</title>

	<para>
	  If a dependency problem arises, &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,
	  all of them will be chosen).  On the other hand, if you
	  <firstterm>reject</firstterm> an action, the resolver will
	  never choose that action.
	</para>

	<para>
	  To reject a solution, highlight it and press
	  <keycap>r</keycap>; the rejection can be cancelled by
	  pressing <keycap>r</keycap> again.  Similarly, select an
	  action and press <keycap>a</keycap> to approve it.  You can
	  undo either action by using &undo-undo; while the resolver
	  screen is active.  If you cancel a rejection or an approval,
	  any solutions that were ignored will be available the next
	  time that you generate a new solution.
	</para>

	<para>
	  Rejected actions are colored red and marked with an
	  <quote>R</quote>, while approved actions are colored green
	  and marked with an <quote>A</quote>.  You can see this in
	  the following screenshot, where the action <quote>keep
	  <systemitem>gstreamer0.8-cdparanoia</systemitem> at its
	  current version</quote> has been rejected, and the action
	  <quote>keep <systemitem>sound-juicer</systemitem> at its
	  current version</quote> has been approved.
	</para>

	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref='images/solution-reject-and-approve-snapshot.png' format='PNG' 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 generated a new solution.  If there
	  is no number in parentheses (for instance, the indicator
	  reads <literal>[1/5]</literal>), then there are no more
	  solutions to generated.  At any time, you can select the
	  last generated solution by pressing <keycap>&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='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='configKeepSuggests'>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='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
	terms; 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 tilde
	character (<quote>~</quote>), followed by a character identifying the type
	of term, and then any additional text required by the term.
      </para>

      <para>
	By default, patterns are checked against all versions of the
	package.  However, some patterns will restrict which versions
	are tested.  For instance, the <link
	linkend='searchDep'><literal>~D</literal></link> pattern takes
	another pattern as an argument, and matches any package that
	depends on another package matching that pattern.  In this
	case, only package versions that satisfy the dependency will
	be tested against.  The versions that are used to test for a
	match will only change in match terms that have a subterm
	(like <link linkend='searchDep'><literal>~D</literal></link>).
      </para>

      <para>
	Most textual searches (for package names, descriptions, etc)
	are performed using case-insensitive <ulink
	url='http://sitescooper.org/tao_regexps.html'>regular
	expressions</ulink>.  This means that you must
	backslash-escape regular expression metacharacters
	<footnote>
	  <para>
	    Regular expression metacharacters include:
	    <quote>+</quote>, <quote>-</quote>, <quote>.</quote>,
	    <quote>(</quote>, <quote>)</quote>, <quote>|</quote>,
	    <quote>[</quote>, <quote>]</quote>, <quote>^</quote>,
	    <quote>$</quote>, and <quote>?</quote>.  Note that some of
	    these are also &aptitude; metacharacters, so if you want
	    to type (for instance) a literal <quote>|</quote>, it must
	    be double-escaped: <quote><literal>\~|</literal></quote>.
	  </para>
	</footnote>
	in searches (for instance, to find <quote>g++</quote>, you should use the
	pattern <quote>g\+\+</quote>).
      </para>

      <para>
	Normally, <quote>whitespace</quote> -- that is, space
	characters, tabs, and so on -- separates terms but is
	otherwise ignored by &aptitude;.  To include whitespace (or
	other special characters) in a term, you can either place a
	tilde in front of it (as in <literal>Debian~
	Project</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>

      <para>
	The following types of terms are available:
      </para>

      <variablelist>
	<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 <literal>~n</literal>
		matcher (described below); for instance,
		<quote><literal>~napti~ntude</literal></quote>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>!<replaceable>term</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which do <emphasis>not</emphasis> match
	      the term <replaceable>term</replaceable>.  For instance,
	      <quote><literal>!~b</literal></quote> selects packages that are not
	      <quote>broken</quote>.
	    </para>

	    <note>
	      <para>
		To include a <quote>!</quote> in a regular expression, it must be
		<quote>escaped</quote> to prevent &aptitude; from considering it
		part of a NOT term: <quote><literal>~!</literal></quote>.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal><replaceable>term1</replaceable> | <replaceable>term2</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages that match either
	      <replaceable>term1</replaceable> or
	      <replaceable>term2</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>term</replaceable>)</literal></term>

	  <listitem>
	    <para>
	      Matches <replaceable>term</replaceable>; this is useful
	      to explicitly select the grouping of complex
	      expressions.  For instance,
	      <quote><literal>~D(perl|python)</literal></quote> matches any package
	      that depends on a package whose name contains either
	      <literal>perl</literal> or <literal>python</literal>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>~Atesting</literal></quote> matches any
	      package available from the <literal>testing</literal>
	      archive.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>~aupgrade</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>~U</literal>).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchBrokenType'>
	  <term><literal>~B<replaceable>type</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which have an unfulfilled (<quote>broken</quote>)
	      dependency of the given <replaceable>type</replaceable>.
	      <replaceable>type</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>conflicts</literal></quote>, or
	      <quote><literal>replaces</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>~b</literal></term>

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

	<varlistentry>
	  <term><literal>~C<replaceable>term</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches packages which conflict with a package matching
	      the given <replaceable>term</replaceable>.  For
	      instance, <quote><literal>~C~mdburrows@debian.org</literal></quote>
	      matches any package which conflicts with a package I
	      maintain.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>~D<optional>B</optional><optional><replaceable>type</replaceable>:</optional><replaceable>term</replaceable></literal></term>

	  <listitem>
	    <para>
	      <replaceable>type</replaceable> may be either
	      <quote><literal>provides</literal></quote> or one of the
	      dependency types given in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>~B</literal></link>.  If
	      <replaceable>type</replaceable> is not present, it
	      defaults to <literal>depends</literal>.  If
	      <literal>B</literal> is present, only broken
	      dependencies will be considered.
	    </para>

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

	<varlistentry>
	  <term><literal>~d<replaceable>description</replaceable></literal></term>

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

	<varlistentry>
	  <term><literal>~E</literal></term>

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

	<varlistentry>
	  <term><literal>~F</literal></term>

	  <listitem>
	    <para>
	      This term does not match any package (<quote>F</quote> stands for
	      <quote>false</quote>).
	      <footnote>
		<para>
		  This is provided largely for symmetry with
		  <literal>~T</literal>.
		</para>
	      </footnote>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>
	  <term><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>~Ggame::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>
	  <term><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>
	  <term><literal>~M</literal></term>

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

	<varlistentry>
	  <term><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>~mjoeyh</literal></quote> will find all packages
	      maintained by Joey Hess.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>~N</literal></term>

	  <listitem>
	    <para>
	      Matches packages which are <quote>new</quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>~n^lib</literal></quote> are libraries of one sort or
	      another.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>!~Odebian</literal></quote> will find
	      any unofficial packages on your system (packages not
	      from the Debian archive).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>~P<replaceable>term</replaceable></literal></term>

	  <listitem>
	    <para>
	      Matches package versions which provide a package that
	      matches the <replaceable>term</replaceable>.  For
	      instance,
	      <quote><literal>~Pmail-transport-agent</literal></quote>
	      will match all the packages that provide
	      <quote><literal>mail-transport-agent</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><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>~prequired</literal></quote> matches
	      packages whose priority is
	      <quote><literal>required</literal></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>~R<optional>B</optional><optional><replaceable>type</replaceable>:</optional><replaceable>term</replaceable></literal></term>

	  <listitem>
	    <para>
	      <replaceable>type</replaceable> may be either
	      <quote><literal>provides</literal></quote> or one of the
	      dependency types given in <link
	      linkend='searchBrokenType'>the documentation of
	      <literal>~B</literal></link>.  If
	      <replaceable>type</replaceable> is not present, it
	      defaults to <literal>depends</literal>.  If
	      <literal>B</literal> is present, only broken
	      dependencies will be considered.
	    </para>

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

	<varlistentry>
	  <term>
	    <literal>~S <replaceable>filter</replaceable> <replaceable>term</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>term</replaceable>.  The string value of
	      the match is the string value of
	      <replaceable>term</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <literal>~s<replaceable>section</replaceable></literal>
	  </term>

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

	<varlistentry>
	  <term>
	    <literal>~T</literal>
	  </term>

	  <listitem>
	    <para>
	      This term matches any package.  For instance,
	      <quote><literal>~i~P~T</literal></quote> matches installed packages
	      which are provided by any package.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id='searchTask'>
	  <term>
	    <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>
	  <term>
	    <literal>~U</literal>
	  </term>

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

	<varlistentry>
	  <term>
	    <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>~Vdebian</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>
	  <term>
	    <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>~v!~P~T</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>
	  <term>
	    <literal>~W<replaceable>term</replaceable></literal> 
	  </term>

	  <listitem>
	    <para>
	      <quote>Widens</quote> the match: if the versions to
	      match against have been limited by an enclosing matcher
	      (such as <link
	      linkend='searchDep'><literal>~D</literal></link>), these
	      limits are dropped.  Thus,
	      <literal>~W<replaceable>term</replaceable></literal>
	      matches a package version if
	      <replaceable>term</replaceable> matches
	      <emphasis>any</emphasis> version of that package.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </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.
	  </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.
	  </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>6</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>6</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 the program, currently
		<quote><computeroutput>&VERSION;</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%N</literal></seg>
	      <seg>Program Name</seg>
	      <seg>The length of the program name.</seg>
	      <seg>No</seg>
	      <seg>
		Outputs the program name; usually
		<quote><computeroutput>aptitude</computeroutput></quote>.
	      </seg>
	    </seglistitem>

	    <seglistitem>
	      <seg><literal>%o</literal></seg>
	      <seg>Download Size</seg>
	      <seg>15</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>10</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>10</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>7</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>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>, ...</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>.
		</para>

		<para>
		  For instance, <literal>pattern(~m => \1)</literal>
		  will group packages according to their Maintainer
		  field.  The policy <literal>pattern(~m)</literal>
		  will do the same thing, as the absent
		  <replaceable>title</replaceable> defaults to
		  <literal>\1</literal>.
		</para>

		<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.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term><literal>topdir</literal></term>

		    <listitem>
		      <para>
			Group based on the part of the Section field
			before the <quote><literal>/</literal></quote>; if there is
			no <literal>/</literal>,
			<literal>main</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 <quote><literal>/</literal></quote>; if there is
			no <literal>/</literal>, the entire field will
			be used.
		      </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>Installed</para></listitem>
		  <listitem><para>Not Installed</para></listitem>
		  <listitem><para>Security Updates</para></listitem>
		  <listitem><para>Upgradable</para></listitem>
		  <listitem><para>Obsolete</para></listitem>
		  <listitem><para>Virtual</para></listitem>
		</itemizedlist>
	      </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 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>.
	  </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>pagedown,C-f</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>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 the program 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 the program: 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>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>
		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>
		Default values stored in
		<filename>/usr/share/aptitude/aptitude-defaults</filename>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		Default values built into the program.
	      </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='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='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='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-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 select it
		for installation.
	      </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-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-Ignore-Trust-Violations'>
	      <seg><literal>Aptitude::CmdLine::Ignore-Trust-Violations</literal></seg>
	      <seg><literal>false</literal></seg>
	      <seg>
		In command-line mode, causes the program 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-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-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-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-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-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-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-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-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 the program 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-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='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='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-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='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='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='configKeepRecommends'>
	      <seg><literal>Aptitude::Keep-Recommends</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, then
		packages will be kept on the system as long as any
		installed package recommends them, even if
		<literal><link
		linkend='configRecommends-Important'>Aptitude::Recommends-Important</link></literal>
		is <literal>false</literal>.
	      </seg>
	    </seglistitem>

	    <seglistitem id='configKeepSuggests'>
	      <seg><literal>Aptitude::Keep-Suggests</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		If this option is <literal>true</literal>, &aptitude;
		will keep automatically installed packages on the
		system as long as any installed package suggests them.
		For more information, see <xref
		linkend='secAutoInstall'/>.
	      </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 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='configParseDescriptionBullets'>
	      <seg><literal>Aptitude::Parse-Description-Bullets</literal></seg>

	      <seg><literal>false</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='configRecommends-Important'>
	      <seg><literal>Aptitude::Recommends-Important</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>, installing a new package will
		also install any packages that it recommends.
		Furthermore, if this option is
		<literal>true</literal>, then packages will be kept on
		the system if an installed package recommends them.
	      </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.
	      </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-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-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-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-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-MaxSuccessors'>
	      <seg><literal>Aptitude::ProblemResolver::Max-Successors</literal></seg>
	      <seg><literal>0</literal></seg>
	      <seg>
		When new possible solutions are being generated, this
		value controls how long the generation procedure
		lasts.  Successors are generated in discrete bundles,
		and as soon as at least one and at most
		<replaceable>Max-Successors</replaceable> nodes have
		been generated, successor generation terminates.
		Turning this value up might cause the first few
		generated solutions to have higher scores; on the
		other hand, it might cause each resolver
		<quote>step</quote> to take a long time.
	      </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-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-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-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-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-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 the program
		<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.  The default
		value is large enough to accomodate commonly
		encountered situations, while preventing the program
		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>10</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.
		Typically this should be a negative value.
	      </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='configProblemResolver-WaitSteps'>
	      <seg><literal>Aptitude::ProblemResolver::WaitSteps</literal></seg>
	      <seg><literal>50</literal></seg>
	      <seg>
		The number of resolver steps to perform in the
		foreground before moving the resolution to the
		background thread.  &aptitude; will be unresponsive
		while this computation takes place; decreasing this
		value will make the program more responsive, but may
		cause the progress indicator to appear unnecessarily.
	      </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='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 the program 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='configSuggests-Important'>
	      <seg><literal>Aptitude::Suggests-Important</literal></seg>

	      <seg><literal>false</literal></seg>

	      <seg>
		This is an obsolete option; use <literal><link
		linkend='configKeepSuggests'>Aptitude::Keep-Suggests</link></literal>
		instead.  Setting this option to
		<literal>true</literal> has the same effect as setting
		<literal><link
		linkend='configKeepSuggests'>Aptitude::Keep-Suggests</link></literal>
		to <literal>true</literal>.
	      </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='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='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(subdir,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-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='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='configDownload-Poll-Interval'>
	      <seg><literal>Aptitude::UI::Download-Poll-Interval</literal></seg>

	      <seg><literal>50000</literal></seg>

	      <seg>
		This option gives the interval in milliseconds at
		which the user interface will update its display and
		poll for new input while a download is being
		performed.  Smaller values will make the program more
		responsive, but will consume a larger amount of CPU
		time.
	      </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='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='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::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='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 the program is in
		read-only mode.
	      </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='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 FAQ</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>
	    When a program running in an xterm is using the mouse, the
	    xterm disables text selection.  However, you can override
	    this behavior and perform a selection by holding the
	    <keycap>Shift</keycap> key down.
	  </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 Kapfe</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>
    </variablelist>
  </chapter>

  <reference id='secReference'>
    <title>Command-Line Reference</title>

    &manpage;
  </reference>

</book>