Hello, I have a hard time understanding the current (0.5.4) apt_preferences man page. Since the apt utility is so central to the effective use of Debian, I believe it is important to make apt-centric man pages error-free, unambiguous, and easy to understand. (This should also make them easy to translate.) To give you an idea of the kinds of problems that I see, I've included below my comments just on the first paragraph. 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.) TIA, Susan ===================================================== Comments on paragraph 1 of the apt_preferences man page The first paragraph of the page contains 4 sentences. I've repeated those sentences below, with my comments on each one. 1. "The APT preferences file controls various aspects of the APT system." When the word 'preferences' is used to refer to a literal filename, it should be indicated by a distinctive font. (Given that this man page was written as a Docbook file, presenting the word 'preferences' in a distinct font just requires that it be enclosed in <filename> tags, e.g.: <filename>preferences</filename>.) 2. "It is meant to be user editable and manipulatable from software." 'manipulatable' should be 'manipulable'. This isn't right is it? Only the local system administrator can change the <filename>preferences</filename> file. It cannot be changed by unprivileged users. 3. "The file consists of a number of records formed like the dpkg status file, space seperated sections of text with at the start of each line tags seperated by a colon." Again, 'status' should be in a distinct font, to indicate that it is referring to a literal filename. Also, the full path name should be given: /var/lib/dpkg/status. Alternatively, the user should be referenced to the command "dpkg --status pkgname". In any case, this sentence appears garbled. I think this sentence means: "The preferences file consists of one or more multi-line records, separated from one another by an empty line. Each line of each record has the form: tagname: value where tagname can be one of Package, Pin, or Pin-Priority." (In fact, it appears that the order and presence of these tags is not arbitrary, so the format of the preferences file requires that each record have precisely this format: Package: _value_ Pin: _value_ Pin-Priority: _value_ where _value_ is some replaceable text.) It would be very interesting to know if the preferences file could accomodate comments, and if so, what format they should take. This sentence doesn't say. 4. "It is stored in /etc/apt/preferences." It is clearer (and I think, more correct) to say either: "the full path name of the file is /etc/apt/preferences", or to say "the file is named 'preferences' and is stored in /etc/apt." ==========================================================================
Attachment:
pgpor6yZGlUC9.pgp
Description: PGP signature