Bug#301464: /usr/bin/apt-cache: apt-cache policy output should be documented

[Marc Haber <mh+debian-bugs@zugschlus.de>]

Package: apt
Version: 0.5.28.5
Severity: minor
File: /usr/bin/apt-cache

Hi,

apt-cache policy output is most helpful when debugging upgrade issues,
but is undocumented:

|$ apt-cache  policy exim4
|exim4:
|  Installed: 4.50-4
|  Candidate: 4.50-4
|  Version Table:
| *** 4.50-4 0
|        500 http://debian.debian.zugschlus.de sid/main Packages
|        100 /var/lib/dpkg/status
|     4.44-2 0
|        500 http://debian.debian.zugschlus.de sarge/main Packages

It should be documented how a candidate is determined, and where the
priorities listed in the version table come from. Especially the
difference between the number behind the version number and the number
in front of the URL is byzantine. Please document.

Greetings
Marc


-- System Information:
Debian Release: 3.1
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing')
Architecture: i386 (i686)
Kernel: Linux 2.6.9-zgserver
Locale: LANG=C, LC_CTYPE=de_DE (charmap=ISO-8859-1)

Versions of packages apt depends on:
ii  libc6                       2.3.2.ds1-20 GNU C Library: Shared libraries an
ii  libgcc1                     1:3.4.3-12   GCC support library
ii  libstdc++5                  1:3.3.5-12   The GNU Standard C++ Library v3

-- no debconf information