merged lp:~donkult/apt/sid

[apt.git] / doc / apt_preferences.5.xml

diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml
index 5f8f9fded6654490848619dbf0bf3f62cc826e6d..f08f92b94464a4740382d0e40e894ecd5ea2d517 100644 (file)
--- a/doc/apt_preferences.5.xml
+++ b/doc/apt_preferences.5.xml
@@ -5,6 +5,9 @@
 <!ENTITY % aptent SYSTEM "apt.ent">
 %aptent;
 
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
+%aptverbatiment;
+
 ]>
 
 <refentry>
@@ -66,10 +69,12 @@ You have been warned.</para>
 
 <para>Note that the files in the <filename>/etc/apt/preferences.d</filename>
 directory are parsed in alphanumeric ascending order and need to obey the
-following naming convention: The files have no or "<literal>pref</literal>"
-as filename extension and which only contain alphanumeric,  hyphen (-),
-underscore (_) and period (.) characters - otherwise they will be silently
-ignored.</para>
+following naming convention: The files have either no or "<literal>pref</literal>"
+as filename extension and only contain alphanumeric, hyphen (-),
+underscore (_) and period (.) characters.
+Otherwise APT will print a notice that it has ignored a file if the file
+doesn't match a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
+configuration list - in this case it will be silently ignored.</para>
 
 <refsect2><title>APT's Default Priority Assignments</title>
 
@@ -97,9 +102,19 @@ APT::Default-Release "stable";
 algorithm to set the priorities of the versions of a package.  Assign:
 
 <variablelist>
+<varlistentry>
+<term>priority 1</term>
+<listitem><simpara>to the versions coming from archives which in their <filename>Release</filename>
+files are marked as "NotAutomatic: yes" but <emphasis>not</emphasis> as "ButAutomaticUpgrades: yes"
+like the debian <literal>experimental</literal> archive.</simpara></listitem>
+</varlistentry>
+
 <varlistentry>
 <term>priority 100</term>
-<listitem><simpara>to the version that is already installed (if any).</simpara></listitem>
+<listitem><simpara>to the version that is already installed (if any) and to the versions coming
+from archives which in their <filename>Release</filename> files are marked as "NotAutomatic: yes" and
+"ButAutomaticUpgrades: yes" like the debian backports archive since <literal>squeeze-backports</literal>.
+</simpara></listitem>
 </varlistentry>
 
 <varlistentry>
@@ -116,7 +131,10 @@ algorithm to set the priorities of the versions of a package.  Assign:
 
 <para>If the target release has not been specified then APT simply assigns
 priority 100 to all installed package versions and priority 500 to all
-uninstalled package versions.</para>
+uninstalled package versions, except versions coming from archives which
+in their <filename>Release</filename> files are marked as "NotAutomatic: yes" -
+these versions get the priority 1 or priority 100 if it is additionally marked
+as "ButAutomaticUpgrades: yes".</para>
 
 <para>APT then applies the following rules, listed in order of precedence,
 to determine which version of a package to install.
@@ -241,6 +259,49 @@ Pin-Priority: 500
 
 </refsect2>
 
+<refsect2><title>Regular expressions and glob() syntax</title>
+<para>
+APT also supports pinning by glob() expressions and regular
+expressions surrounded by /. For example, the following
+example assigns the priority 500 to all packages from
+experimental where the name starts with gnome (as a glob()-like
+expression) or contains the word kde (as a POSIX extended regular
+expression surrounded by slashes).
+</para>
+
+<programlisting>
+Package: gnome* /kde/
+Pin: release n=experimental
+Pin-Priority: 500
+</programlisting>
+
+<para>
+The rule for those expressions is that they can occur anywhere
+where a string can occur. Thus, the following pin assigns the
+priority 990 to all packages from a release starting with karmic.
+</para>
+
+<programlisting>
+Package: *
+Pin: release n=karmic*
+Pin-Priority: 990
+</programlisting>
+
+If a regular expression occurs in a <literal>Package</literal> field,
+the behavior is the same as if this regular expression were replaced
+with a list of all package names it matches. It is undecided whether
+this will change in the future, thus you should always list wild-card
+pins first, so later specific pins override it.
+
+The pattern "<literal>*</literal>" in a Package field is not considered
+a glob() expression in itself.
+
+</refsect2>
+
+
+
+
+
 <refsect2>
 <title>How APT Interprets Priorities</title>