Bug#503481: Bug#545294: [doc] apt.conf isn't clear about either :: or {} (was: Undocumented apt.conf syntax change (append feature))

[David Kalnischkies <kalnischkies+debian@gmail.com>]

package apt
severity 503481 normal
merge 545294 503481
retitle 545294 [doc] apt.conf isn't clear about either :: or {}
tags 545294 + patch
thanks

Hi Vincent Lefevre & Mario Holbe,

On 2009-07-02 at 10:14:39, in #535364 , Filippo Giunchedi wrote:
> That's right, but it is referring to either trailing :: or {} (which gives
> implicit ::)
This is exactly the key part of this "issue" here.

> file. Otherwise it is not clear how one should write config files
> (the changelog isn't clear either).
The APT Team has not changed the syntax for years (i guess)
so i would be interested which changelog is not clear here (if any).

The example from the bug #503481:
DPkg::Post-Invoke { "echo 99test1"; };
DPkg::Post-Invoke { "echo 99test2"; };
DPkg::Post-Invoke:: { "echo 99test3"; };
DPkg::Post-Invoke:: { "echo 99test4"; };

Can be rewritten to:
DPkg::Post-Invoke {
    "echo 99test1";
    "echo 99test2";
    :: "echo 99test3";
    :: "echo 99test4";
}
I think this made it clear why "echo 99test3" is never executed -
it is overridden by "echo 99test4".

( It is really a bit strange that apt accepts "::" as a valid option name,
but this is the same category as accepting other completely wrong options,
is reported a few times and will hopefully fixed in the future with a rewrite
of the configuration system, it is just not priority number one... )

The documentation definitely lacks the clear statement that the use
of both syntax's for lists in one line will have an "unexpected" result.
Maybe it is also a misunderstanding that a newer scope entry could
override an older entry with the same name and so the user tries to
say explicit that he wants to append to the list?

I have attached a little documentation patch which tries to be a bit
clearer in what is the use case for :: and {}.
It would be great if you could have a look at it and report back
if it is understandable or if it needs further descriptions.
Anyway: Thanks for reporting the issue! :)


Best regards / Mit freundlichen Grüßen,

David "DonKult" Kalnischkies


=== modified file 'doc/apt.conf.5.xml'
--- doc/apt.conf.5.xml  2009-08-28 08:06:03 +0000
+++ doc/apt.conf.5.xml  2009-09-07 13:52:04 +0000
@@ -90,13 +90,21 @@
    <literal>#include</literal> will include the given file, unless the filename
    ends in a slash, then the whole directory is included.
    <literal>#clear</literal> is used to erase a part of the
configuration tree. The
-   specified element and all its descendents are erased.</para>
+   specified element and all its descendants are erased. This can be
used for example
+   to remove all elements from a list - otherwise the new options
will only be added to
+   the list, because a scope will never override a previously written
scope entry with
+   the same name: It will add new settings to the scope and only
override options with
+   the same name.</para>

    <para>All of the APT tools take a -o option which allows an
arbitrary configuration
    directive to be specified on the command line. The syntax is a full option
    name (<literal>APT::Get::Assume-Yes</literal> for instance)
followed by an equals
    sign then the new value of the option. Lists can be appended too by adding
    a trailing :: to the list name.</para>
+
+   <para>Note that you can use :: only for appending one item per line and
+   that you can not use it in combination with the scope syntax.
+   (The scope syntax implicit insert ::)</para>
  </refsect1>