Merge branch 'pu/patterns' into 'master'

Package patterns

See merge request apt-team/apt!74

3 files changed, 163 insertions, 0 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 7cca4cf81..3060949e5 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -82,6 +82,7 @@ add_docbook(apt-man MANPAGE ALL
         apt-key.8.xml
         apt-mark.8.xml
         apt_preferences.5.xml
+        apt-patterns.7.xml
         apt-secure.8.xml
         apt-sortpkgs.1.xml
         apt-transport-http.1.xml
diff --git a/doc/apt-patterns.7.xml b/doc/apt-patterns.7.xml
new file mode 100644
index 000000000..efd4293dc
--- /dev/null
+++ b/doc/apt-patterns.7.xml
@@ -0,0 +1,161 @@
+<?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.jgunthorpe;
+   &apt-author.team;
+   &apt-email;
+   &apt-product;
+   <!-- The last update date -->
+   <date>2019-08-15T00:00:00Z</date>
+ </refentryinfo>
+
+ <refmeta>
+   <refentrytitle>apt-patterns</refentrytitle>
+   <manvolnum>7</manvolnum>
+   <refmiscinfo class="manual">APT</refmiscinfo>
+ </refmeta>
+
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-patterns</refname>
+    <refpurpose>Syntax and semantics of apt search patterns</refpurpose>
+ </refnamediv>
+
+ <refsect1><title>Description</title>
+   <para>
+   Starting with version 2.0, <command>APT</command> provides support for
+   patterns, which can be used to query the apt cache for packages.
+   </para>
+ </refsect1>
+
+ <refsect1>
+   <title>Logic patterns</title>
+   <para>
+      These patterns provide the basic means to combine other patterns into
+      more complex expressions, as well as <code>?true</code> and <code>?false</code>
+      patterns.
+   </para>
+   <variablelist>
+     <varlistentry><term><code>?and(PATTERN, PATTERN, ...)</code></term>
+     <listitem><para>Selects objects where all specified patterns match.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?false</code></term>
+     <listitem><para>Selects nothing.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?not(PATTERN)</code></term>
+     <listitem><para>Selects objects where PATTERN does not match.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?or(PATTERN, PATTERN, ...)</code></term>
+     <listitem><para>Selects objects where at least one of the specified patterns match.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?true</code></term>
+     <listitem><para>Selects all objects.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+ <refsect1>
+   <title>Package patterns</title>
+   <para>
+   These patterns select specific packages.
+   </para>
+   <variablelist>
+     <varlistentry><term><code>?architecture(WILDCARD)</code></term>
+     <listitem><para>Selects packages matching the specified architecture, which may contain wildcards using any.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?automatic</code></term>
+     <listitem><para>Selects packages that were installed automatically.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?broken</code></term>
+     <listitem><para>Selects packages that have broken dependencies.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?config-files</code></term>
+     <listitem><para>Selects packages that are not fully installed, but have solely residual configuration files left.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?essential</code></term>
+     <listitem><para>Selects packages that have Essential: yes set in their control file.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?exact-name(NAME)</code></term>
+     <listitem><para>Selects packages with the exact specified name.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?garbage</code></term>
+     <listitem><para>Selects packages that can be removed automatically.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?installed</code></term>
+     <listitem><para>Selects packages that are currently installed.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?name(REGEX)</code></term>
+     <listitem><para>Selects packages where the name matches the given regular expression.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?obsolete</code></term>
+     <listitem><para>Selects packages that no longer exist in repositories.</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?upgradable</code></term>
+     <listitem><para>Selects packages that can be upgraded (have a newer candidate).</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>?virtual</code></term>
+     <listitem><para>Selects all virtual packages; that is packages without a version.
+      These exist when they are referenced somewhere in the archive,
+      for example because something depends on that name.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+
+
+ <refsect1><title>Examples</title>
+   <variablelist>
+     <varlistentry><term><code>apt remove ?garbage</code></term>
+     <listitem><para>Remove all packages that are automatically installed and no longer needed - same as apt autoremove</para></listitem>
+     </varlistentry>
+     <varlistentry><term><code>apt purge ?config-files</code></term>
+     <listitem><para>Purge all packages that only have configuration files left</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Migrating from aptitude</title>
+   <para>
+   Patterns in apt are heavily inspired by patterns in aptitude, but with some tweaks:
+   </para>
+   <itemizedlist>
+      <listitem>
+         <para>Only long forms &mdash; the ones starting with ? &mdash; are supported</para>
+      </listitem>
+      <listitem>
+         <para>
+            Syntax is uniform: If there is an opening parenthesis after a term, it is always assumed to be the beginning of an argument list.
+         </para>
+         <para>
+            In aptitude, a syntactic form <code>"?foo(bar)"</code> could mean <code>"?and(?foo,bar)"</code> if foo does not take an argument. In APT, this will cause an error.
+         </para>
+      </listitem>
+      <listitem>
+         <para>Not all patterns are supported.</para>
+      </listitem>
+      <listitem>
+         <para>Some additional patterns are available, for example, for finding gstreamer codecs.</para>
+      </listitem>
+      <listitem>
+         <para>Escaping terms with <code>~</code> is not supported.</para>
+      </listitem>
+      <listitem>
+         <para>A trailing comma is allowed in argument lists</para>
+      </listitem>
+   </itemizedlist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>
+   &apt-get;, &apt;
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+</refentry>
diff --git a/doc/po4a.conf b/doc/po4a.conf
index 587215abc..1cf170b80 100644
--- a/doc/po4a.conf
+++ b/doc/po4a.conf
@@ -30,6 +30,7 @@
 [type: manpage] apt-transport-http.1.xml $lang:$lang/apt-transport-http.$lang.1.xml add_$lang:xml.add
 [type: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$lang.1.xml add_$lang:xml.add
 [type: manpage] apt-transport-mirror.1.xml $lang:$lang/apt-transport-mirror.$lang.1.xml add_$lang:xml.add
+[type: manpage] apt-patterns.7.xml $lang:$lang/apt-patterns.7.xml add_$lang:xml.add
 
 [type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk
 #                add_$lang::$lang/addendum/docbook_$lang.add