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

[Daniel Hartwig]

On 9 March 2013 00:51, Axel Beckert <abe at debian.org> wrote:
> Hi Daniel,
>
> thanks for the prompt reply.

Sure.  Now that we have — in a sense — processed all the existing
bugs, it pays to keep on top of new ones :-).

>
> Daniel Hartwig wrote:
>> 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.

>
>> > * 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.