Bug#117108: apt-preferences man page unclear

[Bill Wohler <wohler@newt.com>]

Package: apt
Version: 0.5.4
Severity: normal
Tags: woody

  [Originally posted to debian-user. Included in entirety for context,
  and additional comments not in the original note are found in square
  brackets, like this one.]

  I asked myself the questions: How do I add the occaisional unstable
  package to my testing system in a better way than downloading debs
  and using dpkg to install them? How do I track packages in testing
  that I originally got out of unstable? Finally, and less often, how
  do I track a particular package in unstable?

  I searched the archives, discovered preferences, and read the
  apt-preferences man page. I came up with this:

    Package: *
    Pin: release a=testing
    Pin-Priority: 600

    Package: *
    Pin: release a=unstable
    Pin-Priority: 80

    Package: netsaint
    Pin: release a=unstable
    Pin-Priority: 601

  I learned that I could install an unstable package by appending
  /unstable to the package name, like this:

    apt-get install netsaint/unstable

  From then on, apt-get update/upgrade should do the Right Thing.
  Right? Does this configuration answer my questions above? 

  [The man page should answer that.]

  The apt-preferences man page is baffling. It definitely needs
  examples (like the one above). It needs better explanations. For
  example, Joey once included this preferences file:

> Package: *
> Pin: release a=testing
> Pin-Priority: 900
> 
> Package: *
> Pin: release o=Debian
> Pin-Priority: -10

  Even after pouring over the apt-preferences man page a few times, I
  have no idea what is meant by the second stanza.

  [The explanation of the Pin-Priority field is very clear, although
  specific suggestions of priorities to use would be welcome. The
  description of the Pin field is the most baffling part of the man
  page and requires the most attention.]

  Examples should be added to /usr/share/doc/apt as well.

  [That this feature exists in the code rocks, thanks! Better
  documentation will allow us to access it fully.]

-- System Information
Debian Release: woody
Architecture: i386
Kernel: Linux gbr.newt.com 2.4.10-686 #1 Sat Sep 29 19:30:50 EST 2001 i686
Locale: LANG=C, LC_CTYPE=en_US

Versions of packages apt depends on:
ii  libc6                  2.2.4-3           GNU C Library: Shared libraries an
ii  libstdc++2.10-glibc2.2 1:2.95.4-0.011006 The GNU stdc++ library