[Aptitude-devel] Bug#702565: aptitude-doc-en: Multiple minor issues in the resolver documentation

[Manuel A. Fernandez Montecelo]

Control: tags -1 + moreinfo


Hi Axel,

>>> On 8 March 2013 20:30, Axel Beckert <abe at debian.org> wrote:
>>> > Package: aptitude-doc-en
>>> > Severity: minor
>>> > Version: 0.6.8.2-1
>>> >
>>> > Hi,
>>> >
>>> > while trying to understand more of Aptitude's resolver and how to tweak
>>> > it, I noticed the following issues with the documentation, mostly in
>>> > http://people.debian.org/~abe/aptitude/en/ch02s03s05.html#secDependencyResolutionHints
>>> >
>>> > * It is not mentioned how multiple Aptitude::ProblemResolver::Hints have
>>> >   to be written down. Do I have to delimit them by commata? Or do consecutiveI have
>>> >   to state Multiple
>>> >   occurrences of this directive?
>>>
>>> I believe this is sufficiently documented.  The section you mention
>>> says (emphasis added):
>>>
>>>  Hints are stored in the apt configuration file, /etc/apt/apt.conf, in
>>>  the configuration _group_ “Aptitude::ProblemResolver::Hints”
>>>
>>> which is followed by a cross-reference to the section _Configuration
>>> file reference_ that defines the term:
>>>
>>>  An option that contains other options is sometimes called a _group_.
>>
>> Granted so far.
>>
>>> and subsequently refers to the apt.conf(5) man page for more
>>> information.
>>
>> That's about three indirections away.
>
>Yes, though ultimately aptitude borrows exactly apts configuration
>system, so it is sensible to defer to their documentation for full
>details.  It is not possible to properly understand aptitude
>configuration without reading apt.conf(5).
>
>>
>>> Together this should be adequate, yes?  It is rather impractical to
>>> repeat discussion of how option groups are specified at every
>>> instance.
>>
>> I don't think discussing the whole thing again is needed, but a small
>> hint towards how groups work would be appreciated. An example covering
>> more than one value (i.e. with full syntax and not only the value,
>> either for the commandline or in apt.conf syntax, probably the latter)
>> would fully suffice.
>
>Ok, lets agree to put a complete example in here.

So can you provide a complete example?  Maybe you still remember what
you meant here, and probably you know about this part better than I do.

You can make the changes directly, but if you don't feel comfortable
with docbook or something (I don't think so) I can help with that.


>>> > * It is mentioned under "increase-safety-cost-to number" that "maximum"
>>> >   and "minimum" are also valid values for e.g.
>>> >   Aptitude::ProblemResolver::Remove-Level. This also seems to work for
>>> >   Aptitude::ProblemResolver::Keep-All-Level (at least with "maximum",
>>> >   see http://bugs.debian.org/702561).
>>> >
>>> >   But this is neither mentioned in the "Configuration file reference" at
>>> >   http://people.debian.org/~abe/aptitude/en/ch02s05s05.html nor in the
>>> >   chapter "Costs in the interactive dependency resolver" at
>>> >   http://people.debian.org/~abe/aptitude/en/ch02s03s04.html where I
>>> >   would expect it.
>>>
>>> The section on costs [ch02s03s04] is documenting components of the
>>> safety cost calculation.  These “special” cost levels are not used in
>>> that calculation, only to reference some limit values when configuring
>>> other parts of the resolver.  IMO the definition is placed
>>> appropriately, although it is an issue that the individual items in
>>> _Configuration file reference_ do neither directly or indirectly
>>> mention that the ‘maximum’ and ‘minimum’ values can be used.
>>
>> The latter is my main point here, yes.
>>
>>> Being mentioned partway through a list any cross-reference would be
>>> unclear, so perhaps just mention the two values everywhere in the
>>> _Configuration file reference_ where they apply?
>>
>> Fine for me.
>
>Ok.

Same here.


Cheers.
-- 
Manuel A. Fernandez Montecelo <manuel.montezelo at gmail.com>