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

[Daniel Hartwig]

On 20 March 2012 03:11, Manuel A. Fernandez Montecelo
<manuel.montezelo at gmail.com> wrote:
> Hello,
>
> Could you please take a look and tell me what's your take on this?
>  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=487438
>
> I think that the remark between state->"current state" and
> action->"planned action" makes sense and it helps to understand what
> apt-based systems do.  I would add the patches.
>

As noone else has commented on the issue before I believe the meaning
must be quite clear to *most* readers of help.txt, or noone else is
reading it.

Changes such as "state" -> "current state" do make the meaning
*slightly* more clear.  Though this is mostly an issue of semantics as
the proposed adjectives do not particularily change the meaning of the
noun.  "State" generally refers to the current state of a thing unless
the context indicates otherwise.  "Action" refers to a change of
state.

Further to this, the terms "state" and "action" are used consistently
in *all* current aptitude documentation and have very precise
meanings, which is explained in the more detailed texts.  IMO a short
explanation of "state" and "action" in help.txt is desirable to
actually changing these terms everywhere--the meaning is already
obvious enough otherwise.


Other changes in the patch are less useful, some of them infact give
wrong information.

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.


> However I don't know if there are unpleasant consequences about this,
> like e.g. the need for all translators to update their help file and
> man page for little benefit, that will outweight adding the patches.
>

As these help.txt files are manually translated, not using po, there
is no immediate consequence for the translated versions (such as
disappearing).

Indeed, the translated versions may even already be quite clear in and
not require any updating.

Therefore updating this file should be fine, from the perspective of
the translations.


Some further comments on the patch:

> +  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".

I don't see the need for this.  It is verbose and there is no reason a
user should expect upgrades to be selected automatically upon startup.

No other programs do this unless explicitly instructed.

The option to mark upgrades automatically is already explained in the manual.


> +   i - install (candidate version)
> +   r - reinstall (current version)
> +   u - upgrade (candidate version)

This is incorrect: neither 'i' or 'u' always indicate an action on the
candidate version.  It is obvious that reinstall acts on the current
version.

Previous discussion in the document of current and candidate versions
makes the meaning of these clear, these additions, beyond being
incorrect, serve only as noise.


Your thoughts on these issues please.


Regards