[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#557637: [doc] apt_preferences(5) does not clearly states that a single version gets several priorities

Package: apt
Version: 0.7.24
Severity: minor
Tags: patch

Hello,

It took me some time to understand how the preferences work, because the
manpage does not clearly explain that a single version of a package gets
several priorities, one for each place where it is available. This was
specially difficult with a french version of the manpage, that incorrectly uses
a singular where the original had a plural.

I suggest to add:
- a note about this fact in the paragraph that introduces the algorithm;
- a reference to “apt-cache policy”, to illustrate it after the algorithm;
- a precision about “apt-get upgrade” and “apt-get install”, that will upgrade
  a package only if the version with the maximal priority is not the same than
  the installed one.

Here is a patch that introduces these modifications in the english, french and
spanish DocBook versions of the apt_preferences(5).

Regards,

-- 
Tanguy Ortolo

-- Package-specific info:

-- (/etc/apt/preferences present, but not submitted) --


-- (/etc/apt/sources.list present, but not submitted) --


-- System Information:
Debian Release: 5.0.3
  APT prefers stable
  APT policy: (990, 'stable'), (500, 'testing'), (50, 'unstable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.30-2-amd64 (SMP w/2 CPU cores)
Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages apt depends on:
ii  debian-archive-keyring       2009.01.31  GnuPG archive keys of the Debian a
ii  libc6                        2.10.1-7    GNU C Library: Shared libraries
ii  libgcc1                      1:4.3.2-1.1 GCC support library
ii  libstdc++6                   4.3.2-1.1   The GNU Standard C++ Library v3

apt recommends no packages.

Versions of packages apt suggests:
pn  apt-doc                   <none>         (no description available)
ii  aptitude                  0.4.11.11-1+b2 terminal-based package manager
ii  bzip2                     1.0.5-1        high-quality block-sorting file co
ii  dpkg-dev                  1.14.25        Debian package development tools
ii  lzma                      4.43-14        Compression method of 7z format in
ii  python-apt                0.7.13.3       Python interface to libapt-pkg
ii  synaptic                  0.63           Graphical package manager

-- no debconf information

diff -ru apt-0.7.20.2+lenny1.old/doc/apt_preferences.5.xml apt-0.7.20.2+lenny1/doc/apt_preferences.5.xml
--- apt-0.7.20.2+lenny1.old/doc/apt_preferences.5.xml	2009-11-23 13:12:14.000000000 +0100
+++ apt-0.7.20.2+lenny1/doc/apt_preferences.5.xml	2009-11-23 13:46:28.000000000 +0100
@@ -74,7 +74,9 @@
 </para>
 
 <para>If the target release has been specified then APT uses the following
-algorithm to set the priorities of the versions of a package.  Assign:
+algorithm to set the priorities of the versions of a package (note the plural:
+a single version can get several priorities, one for each place where it is
+available).  Assign:
 
 <variablelist>
 <varlistentry>
@@ -92,6 +94,8 @@
 <listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
 </varlistentry>
 </variablelist>
+The result of this algorithm can be displayed with the command
+<command>apt-cache policy <replaceable>some-package</replaceable></command>.
 </para>
 
 <para>If the target release has not been specified then APT simply assigns
@@ -119,7 +123,8 @@
 
 <para>In a typical situation, the installed version of a package (priority 100)
 is not as recent as one of the versions available from the sources listed in
-the &sources-list; file (priority 500 or 990).  Then the package will be upgraded
+the &sources-list; file (priority 500 or 990).  Then, if the version of the highest
+priority is not the same than the installed version, the package will be upgraded
 when <command>apt-get install <replaceable>some-package</replaceable></command>
 or <command>apt-get upgrade</command> is executed.
 </para>
diff -ru apt-0.7.20.2+lenny1.old/doc/es/apt_preferences.es.5.sgml apt-0.7.20.2+lenny1/doc/es/apt_preferences.es.5.sgml
--- apt-0.7.20.2+lenny1.old/doc/es/apt_preferences.es.5.sgml	2009-11-23 13:12:14.000000000 +0100
+++ apt-0.7.20.2+lenny1/doc/es/apt_preferences.es.5.sgml	2009-11-23 13:46:26.000000000 +0100
@@ -75,7 +75,9 @@
 
 <para>
 Si se ha especificado una distribuci?n objetivo, APT usa el siguiente
-algoritmo para establecer las prioridades de cada versi?n de un paquete. 
+algoritmo para establecer las prioridades de cada versi?n de un paquete
+(note el plural: un ?nico paquete puede tener m?ltiples prioridades, una
+para cada lugar donde est? disponible). 
 Asigna:
 
 <variablelist>
@@ -94,6 +96,8 @@
 pertenecen a la distribuci?n objetivo.</simpara></listitem>
 </varlistentry>
 </variablelist>
+El resultado de est algoritmo puede consultarse ejecutando
+<command>apt-cache policy <replaceable>alg?n-paquete</replaceable></command>.
 </para>
 
 <para>
@@ -128,7 +132,8 @@
 <para>
 T?picamente, la versi?n instalada del paquete (prioridad 100)
 no es tan reciente como la disponible a trav?s de &sources-list; 
-(prioridad 500 o 990). Entonces el paquete se actualizar? cuando se ejecute
+(prioridad 500 o 990). Entonces, si la versi?n de maxima prioridad
+es distinta de la version instalada, el paquete se actualizar? cuando se ejecute
 <command>apt-get install <replaceable>alg?n-paquete</replaceable></command> o
 <command>apt-get upgrade</command>.
 </para>
diff -ru apt-0.7.20.2+lenny1.old/doc/fr/apt_preferences.fr.5.xml apt-0.7.20.2+lenny1/doc/fr/apt_preferences.fr.5.xml
--- apt-0.7.20.2+lenny1.old/doc/fr/apt_preferences.fr.5.xml	2009-11-23 13:12:14.000000000 +0100
+++ apt-0.7.20.2+lenny1/doc/fr/apt_preferences.fr.5.xml	2009-11-23 13:38:35.000000000 +0100
@@ -73,8 +73,9 @@
 </para>
 <para>
 Quand une distribution par d?faut a ?t? indiqu?e, APT utilise 
-l'algorithme suivant pour d?terminer la priorit? des versions d'un
-paquet&nbsp;:
+l'algorithme suivant pour d?terminer les priorit?s des versions d'un
+paquet (notez le pluriel?: plusieurs priorit?s peuvent ?tre affect?es
+? une seule version, une pour chaque endroit o? elle est disponible)&nbsp;:
 
 <variablelist>
 <varlistentry><term>une priorit? ?gale ? 100</term>
@@ -91,6 +92,8 @@
 qui appartiennent ? la distribution par d?faut.</simpara></listitem>
 </varlistentry>
 </variablelist>
+Le r?sultat de cet algorithme peut ?tre consult? avec la commande
+<command>apt-cache policy <replaceable>paquet</replaceable></command>.
 </para>
 <para>
 Quand aucune distribution par d?faut n'a ?t? indiqu?e, APT affecte
@@ -130,8 +133,9 @@
 <para>
 En g?n?ral, la version install?e d'un paquet (priorit? 100) n'est
 pas aussi r?cente que les versions disponibles dans les sources
-list?es dans le fichier &sources-list; (priorit? 500 ou 990). Et donc le
-paquet sera mis ? niveau avec la commande&nbsp;:
+list?es dans le fichier &sources-list; (priorit? 500 ou 990). Aussi, si
+la version de plus haute priorit? n'est pas la m?me que la version install?e,
+le paquet sera mis ? niveau avec la commande&nbsp;:
 <command>apt-get install <replaceable>paquet</replaceable></command> ou 
 <command>apt-get dist-upgrade</command>.
 </para>
Reply to: