Adding upstream version 2.7.12.upstream/2.7.12

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 187 insertions, 0 deletions

diff --git a/doc/apt.8.xml b/doc/apt.8.xml
new file mode 100644
index 0000000..b897369
--- /dev/null
+++ b/doc/apt.8.xml
@@ -0,0 +1,187 @@
+<?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 % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
+]>
+
+<refentry>
+
+ <refentryinfo>
+   &apt-author.team;
+   &apt-email;
+   &apt-product;
+   <!-- The last update date -->
+   <date>2023-12-28T00:00:00Z</date>
+ </refentryinfo>
+ 
+ <refmeta>
+   <refentrytitle>apt</refentrytitle>
+   <manvolnum>8</manvolnum>
+   <refmiscinfo class="manual">APT</refmiscinfo>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt</refname>
+    <refpurpose>command-line interface</refpurpose>
+ </refnamediv>
+
+ &synopsis-command-apt;
+
+ <refsect1><title>Description</title>
+   <para><command>apt</command> provides a high-level commandline interface for
+      the package management system. It is intended as an end user interface and
+      enables some options better suited for interactive usage by default
+      compared to more specialized APT tools like &apt-get; and &apt-cache;.
+   </para><para>
+   Much like <command>apt</command> itself, its manpage is intended as an end
+   user interface and as such only mentions the most used commands and options
+   partly to not duplicate information in multiple places and partly to avoid
+   overwhelming readers with a cornucopia of options and details.
+   </para>
+
+   <variablelist>
+     <varlistentry><term><option>update</option> (&apt-get;)</term>
+     <listitem><para><option>update</option> is used to download package
+	   information from all configured sources. Other commands operate on
+	   this data to e.g. perform package upgrades or search in and display
+	   details about all packages available for installation.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>upgrade</option> (&apt-get;)</term>
+     <listitem><para><option>upgrade</option> is used to install available
+	   upgrades of all packages currently installed on the system from the
+	   sources configured via &sources-list;. New packages will be
+	   installed if required to satisfy dependencies, but existing
+	   packages will never be removed. If an upgrade for a package requires
+	   the removal of an installed package the upgrade for this package
+	   isn't performed.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>full-upgrade</option> (&apt-get;)</term>
+     <listitem><para><literal>full-upgrade</literal> performs the function of
+	   upgrade but will remove currently installed packages if this is
+	   needed to upgrade the system as a whole.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>install</option>, <option>reinstall</option>, <option>remove</option>, <option>purge</option> (&apt-get;)</term>
+     <listitem><para>Performs the requested action on one or more packages
+	   specified via &regex;, &glob; or exact match. The requested action
+	   can be overridden for specific packages by appending a plus (+) to the
+	   package name to install this package or a minus (-) to remove it.
+     </para><para>
+	   A specific version of a package can be selected for installation by
+	   following the package name with an equals (=) and the version of the
+	   package to select. Alternatively the version from a specific release can be
+	   selected by following the package name with a forward slash (/) and
+	   codename (&debian-stable-codename;, &debian-testing-codename;, sid …) or suite name (stable,
+	   testing, unstable). This will also select versions from this release
+	   for dependencies of this package if needed to satisfy the request.
+     </para><para>
+	   Removing a package removes all packaged data, but leaves usually
+	   small (modified) user configuration files behind, in case the
+	   remove was an accident. Just issuing an installation request for the
+	   accidentally removed package will restore its function as before in
+	   that case. On the other hand you can get rid of these leftovers
+	   by calling <command>purge</command> even on already removed
+	   packages. Note that this does not affect any data or configuration
+	   stored in your home directory.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>autoremove</option> (&apt-get;)</term>
+     <listitem><para>
+	   <literal>autoremove</literal> is used to remove packages that were
+	   automatically installed to satisfy dependencies for other packages
+	   and are now no longer needed as dependencies changed or the package(s)
+	   needing them were removed in the meantime.
+     </para><para>
+	   You should check that the list does not include applications you have
+	   grown to like even though they were once installed just as a
+	   dependency of another package. You can mark such a package as manually
+	   installed by using &apt-mark;. Packages which you have installed explicitly
+	   via <command>install</command> are also never proposed for automatic removal.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>satisfy</option> (&apt-get;)</term>
+     <listitem><para><option>satisfy</option> satisfies dependency strings, as
+	  used in Build-Depends. It also handles conflicts, by prefixing an argument
+	  with <literal>"Conflicts: "</literal>.
+     </para><para>Example: <literal>apt satisfy "foo, bar (>= 1.0)" "Conflicts: baz, fuzz"</literal>
+     </para></listitem>
+     </varlistentry>
+
+
+     <varlistentry><term><option>search</option> (&apt-cache;)</term>
+     <listitem><para><option>search</option> can be used to search for the given
+	   &regex; term(s) in the list of available packages and display
+	   matches.  This can e.g. be useful if you are looking for packages
+	   having a specific feature.  If you are looking for a package
+	   including a specific file try &apt-file;.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>show</option> (&apt-cache;)</term>
+     <listitem><para>Show information about the given package(s) including
+	   its dependencies, installation and download size, sources the
+	   package is available from, the description of the packages content
+	   and much more. It can e.g. be helpful to look at this information
+	   before allowing &apt; to remove a package or while searching for
+	   new packages to install.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>list</option></term>
+     <listitem><para><option>list</option> is somewhat similar to <command>dpkg-query --list</command>
+	   in that it can display a list of packages satisfying certain
+	   criteria.  It supports &glob; patterns for matching package names,
+	   &apt-patterns;, as well as options to list installed
+	   (<option>--installed</option>), upgradeable (<option>--upgradeable</option>)
+	   or all available (<option>--all-versions</option>) versions.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>edit-sources</option> (work-in-progress)</term>
+     <listitem><para><literal>edit-sources</literal> lets you edit
+	   your &sources-list; files in your preferred text editor while also
+	   providing basic sanity checks.
+     </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>showsrc, depends, rdepends, policy</option> (summarised in &apt-cache;)</term><listitem><simpara></simpara></listitem></varlistentry>
+     <varlistentry><term><option>source, build-dep, download, changelog, clean, distclean, autoclean</option> (summarised in &apt-get;)</term><listitem><simpara></simpara></listitem></varlistentry>
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Script Usage and Differences from Other APT Tools</title>
+  <para>
+   The &apt; commandline is designed as an end-user tool and it may
+   change behavior between versions. While it tries not to break
+   backward compatibility this is not guaranteed either if a change
+   seems beneficial for interactive use.
+  </para><para>
+   All features of &apt; are available in dedicated APT tools like &apt-get;
+   and &apt-cache; as well.  &apt; just changes the default value of some
+   options (see &apt-conf; and specifically the Binary scope). So you should
+   prefer using these commands (potentially with some additional options
+   enabled) in your scripts as they keep backward compatibility as much as possible.
+   </para>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-get;, &apt-cache;, &sources-list;,
+   &apt-conf;, &apt-config;, &apt-patterns;,
+   The APT User's guide in &guidesdir;, &apt-preferences;, the APT Howto.</para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt</command> returns zero on normal operation, decimal 100 on error.</para>
+ </refsect1>
+ &manbugs;
+</refentry>