Hello,

I suspect the override-style operators (_append, _prepend, _remove) would be
much easier to understand if some motivation was given. The existing
descriptions are also vague in places.

I suggest the following changes:


Add to the end of '3.1.9. Removal (Override Style Syntax)':

  Like _append and _prepend, _remove is deferred until after parsing completes.


Add a new section '3.1.10 Motivation behind the override-style operations':

  An advantage of the override-style operations _append, _prepend, and _remove
  (compared to e.g. += and =+) is that they provide "guaranteed" operations.
  For example, consider a class foo.bbclass that needs to add the value "val"
  to the variable FOO, and a recipe that uses foo.bbclass as follows:
  
    inherit foo
  
    FOO = "initial"
  
  If foo.bbclass uses the '+=' operator, as follows, then the final value of
  FOO will be "initial", which is not what we want:
  
    FOO += "val"
  
  If on the other hand foo.bbclass uses the _append operator, as follows, then
  the final value of FOO will be "initial val", as intended:
  
    FOO_append = " val"
  
  Note {
  It is never necessary to use += together with _append. The following sequence
  of assignments will append "barbaz" to FOO:
  
    FOO_append = "bar"
    FOO_append = "baz"
  
  The only effect of changing the second assignment to
  
    FOO_append += "baz"
  
  is to add a space before "baz" in the appended value (due to how the +=
  operator works).
  }
  
  Another advantage of the override-style operations is that they can be
  combined with other overrides, as described in
  [3.2. Conditional Syntax (Overrides)].


In '3.2.3. Examples', change

  OVERRIDES = "foo"
  A = "Y"
  A_foo_append = "Z"
  A_foo_append += "X"

to

  OVERRIDES = "foo"
  A = "Y"
  A_foo_append = "Z"
  A_foo_append = "X"

and change

  ...leaving the variable set to "Z X"

to
  
  ...leaving the variable set to "ZX"

This avoids tricking people into thinking += is necessary when using _append. I
tested it out to make sure it was correct.

Cheers,
Ulf