[Aptitude-devel] Your opinion about a documentation patch, please

[Daniel Hartwig]

On 20 March 2012 22:30, Manuel A. Fernandez Montecelo
<manuel.montezelo at gmail.com> wrote:
> Hi,
>
> 2012/3/20 Daniel Hartwig <mandyke at gmail.com>:
>> [...]
>> In general, the online help file is meant to be a terse overview of using
>> the software.  It does not need to explain all of the many intricacies of
>> using aptitude, that is what the manual is for.
>>
>>
>> Personally, I am not satisifed with this patch in it's current form.
>
> Would you prefer to reject the patch entirely and not modify this?
>

Yes.

Though, it is worth to salvage the idea of clarifying "state" and
"action".  Not, however, in the way suggested here.

Add a brief note explaining the terms--similar to what is in the
user's manual--then close this report and be done with it.

>
>>> +  Please note that starting of aptitude in default mode does not set "planned
>>> +action" to "upgrade" on all upgradable packages.  You must explicitly press
>>> +"U".
>>

> To be honest, it struck to me as strange that a Debian Developer was
> confused about this, where for me these things were already well
> known, so I guess that he's not the only one having problem
> understanding things.
>

If you ask ten people about what they find confusing and would like
added to help.txt you will get ten different answers.  As a brief
overview of using the interface it is not possible to cater to
everyone in this file.  As long as the reader is directed to the full
documentation then they can take their questions there.

The more added to the file it becomes harder to quickly lookup
information ("what was the key to change display limit?").  It also
becomes closer to being the user's manual, at which point you may as
well just open that up instead.


Regards