Update Status field values handling

[apt.git] / doc / apt.8.xml

diff --git a/doc/apt.8.xml b/doc/apt.8.xml
index bb1f6bb91505b7606475823b25e160976d5df31d..29bf96751832bb997d84a3aa934476fa7cda4eeb 100644 (file)
--- a/doc/apt.8.xml
+++ b/doc/apt.8.xml
@@ -1,13 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-
-<!ENTITY % aptent SYSTEM "apt.ent">
-%aptent;
-
-<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
-%aptverbatiment;
-
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
 ]>
 
 <refentry>
@@ -29,13 +25,15 @@
  <!-- Man page title -->
  <refnamediv>
     <refname>apt</refname>
-    <refpurpose>APT package -- command-line interface</refpurpose>
+    <refpurpose>command-line interface</refpurpose>
  </refnamediv>
 
  &synopsis-command-apt;
 
  <refsect1><title>Description</title>
-   <para><command>apt</command> is the command-line tool for handling packages. It provides a commandline interface for the package management of the system.
+   <para><command>apt</command> (Advanced Package Tool) is the
+   command-line tool for handling packages. It provides a commandline
+   interface for the package management of the system.
 
    See also &apt-get; and &apt-cache; for more low-level command options.
    </para>
@@ -43,10 +41,10 @@
    <variablelist>
      <varlistentry><term><option>list</option></term>
      <listitem><para><literal>list</literal> is used to
-     display a list of packages. It supports shell pattern for matching
+     display a list of packages. It supports shell pattern for matching 
      package names and the following options:
-       <option>--installed</option>
-       <option>--upgradable</option>
+       <option>--installed</option>, 
+       <option>--upgradable</option>, 
        <option>--all-versions</option>
      are supported.
      </para></listitem>
@@ -103,8 +101,15 @@
      <listitem><para><literal>upgrade</literal> is used to install the
      newest versions of all packages currently installed on the system
      from the sources enumerated in
-     <filename>/etc/apt/sources.list</filename>. New package will be
-     installed, but existing package will never removed.
+     <filename>/etc/apt/sources.list</filename>. New packages will be
+     installed, but existing packages will never be removed.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>full-upgrade</option></term>
+     <listitem><para><literal>full-upgrade</literal> performs the
+     function of upgrade but may also remove installed packages
+     if that is required in order to resolve a package conflict.
      </para></listitem>
      </varlistentry>
 
@@ -122,30 +127,48 @@
    </variablelist>
  </refsect1>
 
+ <refsect1><title>Script usage</title>
+  <para>
+   The &apt; commandline is designed as a end-user tool and it may
+   change the output between versions. While it tries to not break
+   backward compatibility there is no guarantee for it either.
+   All features of &apt; are available in  &apt-cache; and &apt-get;
+   via APT options. Please prefer using these commands in your scripts.
+  </para>
+ </refsect1>
+
  <refsect1><title>Differences to &apt-get;</title>
  <para>The <command>apt</command> command is meant to be pleasant for
- end users and does not need to be backward compatilbe like
+ end users and does not need to be backward compatible like
  &apt-get;. Therefore some options are different:
  
  <itemizedlist>
-   <listitem>The option <literal>DPkgPM::Progress-Fancy</literal> is enabled.
+   <listitem>
+     <para>The option <literal>DPkg::Progress-Fancy</literal> is enabled.
+     </para>
    </listitem>
-   <listitem>The option <literal>APT::Color</literal> is enabled.
+   <listitem>
+     <para>The option <literal>APT::Color</literal> is enabled.
+     </para>
    </listitem>
-   <listitem>A new <literal>list</literal> command is available
-   similar to <literal>dpkg --list</literal>.
+   <listitem>
+     <para>A new <literal>list</literal> command is available
+     similar to <literal>dpkg --list</literal>.
+     </para>
    </listitem>
-   <listitem>The option <literal>upgrade</literal> has
-   <literal>--with-new-pkgs</literal> enabled by default.
+   <listitem>
+     <para>The option <literal>upgrade</literal> has
+     <literal>--with-new-pkgs</literal> enabled by default.
+     </para>
    </listitem>
 
  </itemizedlist>
-
  </para>
+
  </refsect1>
 
  <refsect1><title>See Also</title>
-   <para>&apt-get; &apt-cache;, &sources-list;,
+   <para>&apt-get;, &apt-cache;, &sources-list;,
    &apt-conf;, &apt-config;, 
    The APT User's guide in &guidesdir;, &apt-preferences;, the APT Howto.</para>
  </refsect1>