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

[Daniel Hartwig]

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

and subsequently refers to the apt.conf(5) man page for more
information.

Together this should be adequate, yes?  It is rather impractical to
repeat discussion of how option groups are specified at every
instance.

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

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?  Any other
suggestions?

Regards