Bug#115517: apt_preferences man page update (draft)

[Thomas Hood <jdthood@yahoo.co.uk>]

severity 115517 minor
severity 131623 minor
severity 117108 minor
merge 115517 131623 154224 155381 157789 117108
thanks

Recently I tried to figure out how APT pinning works
by reading the apt_preferences(5) man page.  I found the page
quite confusing, so I took a stab at editing it.  I tried
to address all of the bug reports mentioned above.

Unfortunately I am not sure that I have interpreted the 
original correctly since (as I mentioned) I am trying to
figure out how the thing works.  So please read through
my draft to make sure everything is correct.  Please feel
free to make corrections and improvements.  I originally
tried sending this to the maintainer listed in the man page
itself, but the address doesn't work.

I am merging all the reports of shortcomings in the a_p
man page.  Please follow up to #115517.

Here's the file, then a diff against the version of the man
page in 0.5.4.                                // Thomas Hood


.\" This manpage has been automatically generated by docbook2man-spec
.\" from a DocBook document.  docbook2man-spec can be found at:
.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "APT_PREFERENCES" "5" "22 September 2002" "" ""
.SH NAME
apt_preferences \- Preference control file for APT
.SH "DESCRIPTION"
.PP
The APT preferences file controls various aspects of the APT system. 
It is meant to be user-editable and manipulable from software. The file
consists of a number of records formed like those in the dpkg status file:
space-separated sections of text with tags at the start of each line
followed by a colon. It is stored in \fI/etc/apt/preferences\fR.
.SH "VERSIONING"
.PP
One purpose of the preferences file is to let the user select which version
of a package will be installed.  This selection can be made in a number of
ways: by version, by release and/or by source. 
.PP
Selection by version can be either exact (e.g., 2.1.3) or by
prefix pattern (e.g., 2.1*).  Such a pattern can be used, e.g.,
to ignore the Debian revision level (i.e., the part of
the version identifier beginning with the hyphen).
When several version identifiers match the prefix pattern, the
latest version will always be chosen.
.PP
Selection by release takes three forms.  The first two forms are 
shortcuts intended for quick command-line use.  If the first
character of the specification is a digit then it is considered
to be a release-version specifier; otherwise it is considered 
to be a release-label specifier.  However, if the specification
contains the equals sign then it is considered to be a
release-property specification.  A release-property specification
is a comma-separated list of one-letter keys each followed by an
equals sign and a string.  Some examples of release-property
specifications:
.PP
.sp
.nf
v=2.1*,o=Debian,c=main
l=Debian
a=stable
.sp
.fi
.PP
The properties specified are determined by the \fIRelease\fR files
that APT downloads during an update. The possible keys are:
.TP
\fBa= Archive\fR
This selects the archive, e.g., stable or unstable.
The special string "now" is used to designate the set of packages
that are currently installed.
.TP
\fBc= Component\fR
This selects the component of the archive, e.g., main or contrib.
This selector may be omitted if there are no components for this archive.
.TP
\fBv= Version\fR
This selects the version of the release, e.g., 2.1.3.
.TP
\fBo= Origin\fR
This specifies the origin of the packages. In the case of Debian
the origin is "Debian".
.TP
\fB\fR
.TP
\fBl= Label\fR
This specifies the encompassing label of the distribution.
For Debian proper this field reads "Debian".  For derived distributions
it should contain the proper name of the distribution.
.PP
.PP
The final selection method is by source. This is simply the name
of the site where the package files were obtained.  The empty string
is used for file URIs.
.PP
Version selection is used in many different parts of APT, not just in
the preferences file.
.SH "CANDIDATE VERSION POLICY"
.PP
When multiple sources are named in \fB\fIsources.list\fB\fR(5),
APT maintains an internal list of all available versions of each package.
.PP
In order to decide which version of a package to select, APT assigns a
priority to each available version.  It then identifies the highest priority
version that is later than the installed version of the package, and the
highest priority version that is earlier than the installed version.
If the earlier version has a priority of 1000 or less then it is ignored.
However, if it has a priority greater than 1000 then the priority is
compared with the priority of the later versions and the package
with the highest priority wins.
.PP
It is possible to think of the priorities in strata:
.TP
\fB1000 and up\fR
Priorities that can induce downgrade
.TP
\fB100 to 1000\fR
Ordinary priorities.
990 is the priority set by the \fB--target-release \fR \fBapt-get\fR(8) option.
989 is the maximum value for automatic priorities.
500 is the priority of the default package files.
.TP
\fB100\fR
Priority of the currently installed version
.TP
\fB0 to 100\fR
Non-automatic priorities. Packages of these priorities are
only selected if the package is not already installed and
there is no other version available.
.TP
\fBless than 0\fR
Priority of a version never to be selected
.PP
.PP
Each package may be pinned at a specific version.
Giving the pin-version a priority greater than 1000 will allow
APT to downgrade in order to get to that version.
.PP
Pinning a package at a particular version is done like this:
.PP
.sp
.nf
Package: apt
Pin: version 0.4.0
Pin-Priority: 1001
.sp
.fi
The first line specifies the package, the second specifies the pin version
and the last gives the priority of this pin. The first word of the pin
specification may be "version", "release" or "origin"; the remainder of
the field is as described in the Versioning section above.
.PP
A default pin may be specified for all the packages listed in a Packages
file as follows.
.PP
.sp
.nf
Package: *
Pin: release v=2.1*
Pin-Priority: 998
.sp
.fi
The first word of the default pin specification may be "release" or "origin".
Any number of such specifications may be given; the first one that
applies will be used.
If the Pin-Priority field is omitted then the priority defaults to 989.
.PP
Sources such as \fIproject/experimental\fR are marked
"Not Automatic" and fall to the bottom of the selection pile.
.SS "INTERESTING EFFECTS"
.PP
A downgrade is not preformed unless the version to install has
priority greater than 1000.  Note that it is therefore possible
that a later, lower priority version will be selected in preference
to an earlier, higher (but not higher than 1000) priority version.
For instance, if package versions 1.2, 1.1 and 1.0 of package foo
are available with 1.1 is currently installed, and the priorities of
the versions are 900, 100 and 950 repectively, then the winning
version will be 1.2.
.PP
In practice this is often desired. A user may use a default pin to
make the stable distribution the default and then use the 
\fB--target-release\fR option with \fBapt-get\fR(8) to install newer
versions of packages from unstable. The packages that have thus been
upgraded to unstable will not be downgraded subsequently (unless their
priority is set to less than 100), since the stable versions have
priorities that fall below the downgrade prevention barrier.
.PP
Users of third-party add-ons such as Helix GNOME can use this mechanism to
force the selection of Helix packages, or of Debian packages, by setting
the priority of the preferred origin sufficiently high. It is even
possible to mass downgrade from one set of packages to another by
setting a priority larger than 1000.
.SH "EXAMPLES"
This example apt preferences file causes the system to
track testing.
Packages may be upgraded individually to their unstable versions,
and apt will then track the unstable version.
(Remember to list both testing and unstable in your sources.list file.)
.sp
.nf
Package: *
Pin: release a=testing
Pin-Priority: 900
.PP
Package: *
Pin: release o=Debian
Pin-Priority: -10
.sp
.fi
.SH "SEE ALSO"
.PP
\fBapt-cache\fR(8) \fB\fIapt.conf\fB\fR(5)
.SH "BUGS"
.PP
See the APT bug page <URL:http://bugs.debian.org/apt>. 
If you wish to report a bug in APT, please see 
\fI/usr/share/doc/debian/bug-reporting.txt\fR or the \fBbug\fR(1) command.
.SH "AUTHOR"
.PP
APT was written by the APT team <apt@packages.debian.org>.

--- /tmp/apt_preferences.5	Sun Aug 19 03:03:45 2001
+++ apt_preferences.5	Sun Sep 29 23:16:09 2002
@@ -3,37 +3,39 @@
 .\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
 .\" Please send any bug reports, improvements, comments, patches, 
 .\" etc. to Steve Cheng <steve@ggi-project.org>.
-.TH "APT_PREFERENCES" "5" "12 March 2001" "" ""
+.TH "APT_PREFERENCES" "5" "22 September 2002" "" ""
 .SH NAME
 apt_preferences \- Preference control file for APT
 .SH "DESCRIPTION"
 .PP
 The APT preferences file controls various aspects of the APT system. 
-It is meant to be user editable and manipulatable from software. The file
-consists of a number of records formed like the dpkg status file, space
-seperated sections of text with at the start of each line tags seperated 
-by a colon. It is stored in \fI/etc/apt/preferences\fR.
+It is meant to be user-editable and manipulable from software. The file
+consists of a number of records formed like those in the dpkg status file:
+space-separated sections of text with tags at the start of each line
+followed by a colon. It is stored in \fI/etc/apt/preferences\fR.
 .SH "VERSIONING"
 .PP
 One purpose of the preferences file is to let the user select which version
-of a package will be installed. This selection can be made in a number of
-ways that fall into three categories, version, release and origin. 
+of a package will be installed.  This selection can be made in a number of
+ways: by version, by release and/or by source. 
 .PP
-Selection by version can be done by exact match or prefix match. The format
-is 2.1.2 or 2.2* for a prefix match. Matching by prefix 
-can be used to ignore the r in the Debian release versioning, like
-2.1r* or to ignore Debian specific revisions, 1.1-*.
-When matching versions with a prefix the highest matching version will
-always be picked.
-.PP
-Selection by release is more complicated and has three forms. The primary
-purpose of release selections is to identify a set of packages that match
-a specific vendor, or release (ie Debian 2.1). The first two forms are 
-shortcuts intended for quick command line use. If the first character of the
-specification is a digit then it is considered to be a release version match, 
-otherwise a release label match. Specifications which contain equals are
-full release data matches and are a comma seperated list of one letter keys
-followed by an equals then by the string. Examples:
+Selection by version can be either exact (e.g., 2.1.3) or by
+prefix pattern (e.g., 2.1*).  Such a pattern can be used, e.g.,
+to ignore the Debian revision level (i.e., the part of
+the version identifier beginning with the hyphen).
+When several version identifiers match the prefix pattern, the
+latest version will always be chosen.
+.PP
+Selection by release takes three forms.  The first two forms are 
+shortcuts intended for quick command-line use.  If the first
+character of the specification is a digit then it is considered
+to be a release-version specifier; otherwise it is considered 
+to be a release-label specifier.  However, if the specification
+contains the equals sign then it is considered to be a
+release-property specification.  A release-property specification
+is a comma-separated list of one-letter keys each followed by an
+equals sign and a string.  Some examples of release-property
+specifications:
 .PP
 .sp
 .nf
@@ -43,94 +45,81 @@
 .sp
 .fi
 .PP
-The data for these matches are taken from the \fIRelease\fR files
-that APT downloads during an update. The available keys are:
+The properties specified are determined by the \fIRelease\fR files
+that APT downloads during an update. The possible keys are:
 .TP
 \fBa= Archive\fR
-This is the common name we give our archives, such as stable or
-unstable. The special name now is used to designate
-the set of packages that are currently installed.
+This selects the archive, e.g., stable or unstable.
+The special string "now" is used to designate the set of packages
+that are currently installed.
 .TP
 \fBc= Component\fR
-Referes to the sub-component of the archive, main, 
-contrib etc. Component may be omitted if there are no 
-components for this archive.
+This selects the component of the archive, e.g., main or contrib.
+This selector may be omitted if there are no components for this archive.
 .TP
 \fBv= Version\fR
-This is a version string with the same properties as in the Packages file.
-It represents the release level of the archive. Typical Debian release
-numbers look like 2.1r2 with the r designating the release of 
-2.1. New releases are limited to security updates and other important
-changes.
+This selects the version of the release, e.g., 2.1.3.
 .TP
 \fBo= Origin\fR
-This specifies who is providing this archive. In the case of Debian the
-string will read Debian. Other providers may use their own 
-string.
+This specifies the origin of the packages. In the case of Debian
+the origin is "Debian".
 .TP
 \fB\fR
 .TP
 \fBl= Label\fR
-This carries the encompassing name of the distribution. For Debian proper
-this field reads Debian. For derived distributions it should 
-contain their proper name.
+This specifies the encompassing label of the distribution.
+For Debian proper this field reads "Debian".  For derived distributions
+it should contain the proper name of the distribution.
 .PP
 .PP
-The final selection method is by origin. This is simply the site name
-of the originating package files. The empty string is used for file URIs.
+The final selection method is by source. This is simply the name
+of the site where the package files were obtained.  The empty string
+is used for file URIs.
 .PP
-Version selection, particularly the latter two methods, are used in many
-different parts of APT, not just the preferences file.
+Version selection is used in many different parts of APT, not just in
+the preferences file.
 .SH "CANDIDATE VERSION POLICY"
 .PP
-Internally APT maintains a list of all available versions for all packages.
-If you place multiple releases or vendors in your \fB\fIsources.list\fB\fR(5) file then
-these features are available. By default APT selects the highest version
-from all automatic sources. Some sources, such as 
-\fIproject/experimental\fR are marked Not Automatic - these fall 
-to the bottom of the selection pile.
-.PP
-When deciding what version to use APT assigns a priority to each available
-version of the package. It then does two things, first it selects
-the highest priorty version that is newer than the installed version of the 
-package, then it selects the highest priority version that is older than
-the installed version. Next, if the older versions have a priority greater
-than 1000 they are compared with the priority of the upgrade set, the larger
-becomes the selected result. Otherwise the downgrade versions are ignored
-and the highest priority of the ugprade set is selected.
+When multiple sources are named in \fB\fIsources.list\fB\fR(5),
+APT maintains an internal list of all available versions of each package.
+.PP
+In order to decide which version of a package to select, APT assigns a
+priority to each available version.  It then identifies the highest priority
+version that is later than the installed version of the package, and the
+highest priority version that is earlier than the installed version.
+If the earlier version has a priority of 1000 or less then it is ignored.
+However, if it has a priority greater than 1000 then the priority is
+compared with the priority of the later versions and the package
+with the highest priority wins.
 .PP
 It is possible to think of the priorities in strata:
 .TP
 \fB1000 and up\fR
-Downgradable priorities
-.TP
-\fB1000\fR
-The downgrade prevention barrier
+Priorities that can induce downgrade
 .TP
 \fB100 to 1000\fR
-Standard priorities. 990 is the priority set by the 
-\fB--target-release \fR \fBapt-get\fR(8) option. 989 is the start for auto
-priorities and 500 are all the default package files.
+Ordinary priorities.
+990 is the priority set by the \fB--target-release \fR \fBapt-get\fR(8) option.
+989 is the maximum value for automatic priorities.
+500 is the priority of the default package files.
 .TP
 \fB100\fR
-The currently installed version
+Priority of the currently installed version
 .TP
 \fB0 to 100\fR
-Non automatic priorities. These are only used if the package
-is not installed and there is no other version available.
+Non-automatic priorities. Packages of these priorities are
+only selected if the package is not already installed and
+there is no other version available.
 .TP
 \fBless than 0\fR
-The version is never selected.
-.PP
+Priority of a version never to be selected
 .PP
-Giving a pin a priority greater than 1000 will allow APT to downgrade
-in order to get to that version. 
 .PP
-Each package may be pinned to a specific version and each Packages file
-has a priority for every package inside. The highest priority assigned
-to a package is the one that is used.
+Each package may be pinned at a specific version.
+Giving the pin-version a priority greater than 1000 will allow
+APT to downgrade in order to get to that version.
 .PP
-A package pin looks like this:
+Pinning a package at a particular version is done like this:
 .PP
 .sp
 .nf
@@ -139,15 +128,13 @@
 Pin-Priority: 1001
 .sp
 .fi
-The first line specifies the package, the second gives the Pin specification
+The first line specifies the package, the second specifies the pin version
 and the last gives the priority of this pin. The first word of the pin
-specification may be version, release or origin, the remainder of the field
-is described in the Versioning section above.
+specification may be "version", "release" or "origin"; the remainder of
+the field is as described in the Versioning section above.
 .PP
-A default pin is how the priorities of package files are set. Any number
-of default pins may be specified, the first matching default will select
-the priority of the package file. Only release or origin may be used in 
-the Pin specification since they match Packages files.
+A default pin may be specified for all the packages listed in a Packages
+file as follows.
 .PP
 .sp
 .nf
@@ -156,34 +143,54 @@
 Pin-Priority: 998
 .sp
 .fi
+The first word of the default pin specification may be "release" or "origin".
+Any number of such specifications may be given; the first one that
+applies will be used.
+If the Pin-Priority field is omitted then the priority defaults to 989.
 .PP
-If the Pin-Priority field is omitted then the priority defaults to 989 for
-both cases.
+Sources such as \fIproject/experimental\fR are marked
+"Not Automatic" and fall to the bottom of the selection pile.
 .SS "INTERESTING EFFECTS"
 .PP
-Due to the downgrade prevention barrier at priority 1000 it is possible
-that a lower priority version will be selected if the higher priority 
-would cause a downgrade. For instance, if package foo has versions
-1.2, 1.1 and 1.0 installed, with 
-1.1 being the currently installed version and the priorities of 
-each version being 900, 100 and 950 repectively the winning version will be 
-1.2.
+A downgrade is not preformed unless the version to install has
+priority greater than 1000.  Note that it is therefore possible
+that a later, lower priority version will be selected in preference
+to an earlier, higher (but not higher than 1000) priority version.
+For instance, if package versions 1.2, 1.1 and 1.0 of package foo
+are available with 1.1 is currently installed, and the priorities of
+the versions are 900, 100 and 950 repectively, then the winning
+version will be 1.2.
 .PP
 In practice this is often desired. A user may use a default pin to
 make the stable distribution the default and then use the 
-\fB--target-dist\fR option with \fBapt-get\fR(8) to select newer versions
-from unstable. The packages that have been upgraded to unstable will
-continue to follow the versions that are available in unstable since
-the stable versions now fall below the downgrade prevention barrier.
-.PP
-If this is not desired then a default pin should be used to make unstable
-have a priority less than 100.
-.PP
-Users of 3rd party add ons such as Helix GNOME can use this mechanism to
-force the usage of Helix packages, or force the usage of Debian packages
-by setting the priority of that source sufficiently high. It is even
+\fB--target-release\fR option with \fBapt-get\fR(8) to install newer
+versions of packages from unstable. The packages that have thus been
+upgraded to unstable will not be downgraded subsequently (unless their
+priority is set to less than 100), since the stable versions have
+priorities that fall below the downgrade prevention barrier.
+.PP
+Users of third-party add-ons such as Helix GNOME can use this mechanism to
+force the selection of Helix packages, or of Debian packages, by setting
+the priority of the preferred origin sufficiently high. It is even
 possible to mass downgrade from one set of packages to another by
-using a priority larger than 1000.
+setting a priority larger than 1000.
+.SH "EXAMPLES"
+This example apt preferences file causes the system to
+track testing.
+Packages may be upgraded individually to their unstable versions,
+and apt will then track the unstable version.
+(Remember to list both testing and unstable in your sources.list file.)
+.sp
+.nf
+Package: *
+Pin: release a=testing
+Pin-Priority: 900
+.PP
+Package: *
+Pin: release o=Debian
+Pin-Priority: -10
+.sp
+.fi
 .SH "SEE ALSO"
 .PP
 \fBapt-cache\fR(8) \fB\fIapt.conf\fB\fR(5)