Re: apt_preferences man page

[Bill Wohler <wohler@newt.com>]

Susan Kleinmann <sgk@kleinmann.com> wrote:

> Rather than just kvetch about the man page, I'd like to submit a
> suggested revision.  So, my question is:  would anyone who is really 
> familiar with the apt preferences file be willing to work with me to 
> accomplish this goal?  (This means answering a lot of questions, so I can
> tell if my understanding is correct as I go through the page.)

Susan,

  Thomas Hood <jdthood@yahoo.co.uk> is spearheading an effort to do this
  very thing. Please see
  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=115517 and all of the
  merged reports.

  I haven't quite persuaded Thomas to reorganize the entire page. I
  wrote:

>  The major problem with this document is the organization. The details
>  are discussed first with no context. Even after reading the whole
>  document, it's still hard to figure out how the text fits in. I've got
>  an idea to clean this up.
>
>  The Description ends with the following text:
>
>    The file consists of a number of records formed like those in dpkg
>    status file: blocks of text (stanzas) separated by blank lines; each
>    line of text consisting of a tag followed by a colon and a string.
>    
>  So far so good. The rest of the man page should describe those tags
>  and strings. I would therefore suggest changing the following two
>  sections:
>
>    <RefSect1><Title>Versioning</>
>    <RefSect1><Title>Version Selection Policy</>
>
>  to an alphabetical list of tags (I'm guessing on the SGML):
>
>    <RefSect1><Title>Tags</>
>      <para>The tags that can be used in the preferences file are
>      described in this section.
>    <RefSect2><Title>Package</>
>    <RefSect2><Title>Pin</>
>      [Describe the syntax generally, then introduce the keys a, c, v,
>      o. Create a subsection for each key. The text that is found at the
>      beginning of the current Versioning section is limited to the "v"
>      key and should be moved to that subsection, while the "selection
>      by release" and "selection by source" should be moved to their
>      respective subsections ("a" and "o"?)]
>    <RefSect2><Title>Pin-Priority</>
>      [Describe the syntax generally, and then include the text that is
>      currently in Version Selection Policy.
  

--
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.