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

[Axel Beckert]

Hi Daniel,

thanks for the prompt reply.

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.

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

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

		Regards, Axel
-- 
 ,''`.  |  Axel Beckert <abe at debian.org>, http://people.debian.org/~abe/
: :' :  |  Debian Developer, ftp.ch.debian.org Admin
`. `'   |  1024D: F067 EA27 26B9 C3FC 1486  202E C09E 1D89 9593 0EDE
  `-    |  4096R: 2517 B724 C5F6 CA99 5329  6E61 2FF9 CD59 6126 16B5