Susan Kleinmann <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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.
