[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

apt_preferences man page



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: pgpopI5xwHOQw.pgp
Description: PGP signature


Reply to: