Hi Simon,

Many thanks for the new version of your patch!
See my questions below...

On 12/15/21 10:25 AM, Simon A. Eugster wrote:
> Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> ---
>  .../bitbake-user-manual-metadata.rst          | 28 ++++++++++++-------
>  1 file changed, 18 insertions(+), 10 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index d802a8d3..fc4f5d13 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -300,6 +300,12 @@ It is also possible to append and prepend to shell functions and
>  BitBake-style Python functions. See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`" and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions`"
>  sections for examples.
> 
> +.. note::
> +
> +   Before Honister (3.4), override style used ``_`` instead of ``:``, so you will
> +   still find a lot of documentation using “_append”, “_prepend”, and
> +   “_remove”.
> +


I don't have anything about this text, but I wonder whether we should
mention the old syntax in the current docs.
Thoughts anyone?

>  .. _removing-override-style-syntax:
> 
>  Removal (Override Style Syntax)
> @@ -517,20 +523,22 @@ variable.
>  -  *Selecting a Variable:* The :term:`OVERRIDES` variable is a
>     colon-character-separated list that contains items for which you want
>     to satisfy conditions. Thus, if you have a variable that is
> -   conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the
> +   conditional on "arm", and "arm" is listed in :term:`OVERRIDES`, then the
>     "arm"-specific version of the variable is used rather than the
>     non-conditional version. Here is an example::
> 
> -      OVERRIDES = "architecture:os:machine"
> +      # Typically, OVERRIDES contains something like architecture:os:machine
> +      OVERRIDES = "linux:arm"


Here you quote an example with two items, but this doesn't align with
the typical contents with three items you mention in the comment that
you added.
By the way, according to the below text, didn't you mean?

OVERRIDES = "foo:linux:arm"

It looks like a good idea to have this comment; this way you can give a
concrete example. In my opinion, "foo" is vague, what about instead?

OVERRIDES = "arm:linux:beaglebone"

>        TEST = "default"
> -      TEST_os = "osspecific"
> -      TEST_nooverride = "othercondvalue"
> +      TEST:arm = "armspecific"
> +      TEST:nooverride = "othercondvalue"
> 
> -   In this example, the :term:`OVERRIDES`
> -   variable lists three overrides: "architecture", "os", and "machine".
> -   The variable ``TEST`` by itself has a default value of "default". You
> -   select the os-specific version of the ``TEST`` variable by appending
> -   the "os" override to the variable (i.e. ``TEST_os``).
> +   In this example, the :term:`OVERRIDES` variable lists three
> +   overrides: "foo", "linux", and "arm". The variable ``TEST`` by itself
> +   has a default value of "default", and the value of the “arm” specific
> +   version “armspecific” is used because :term:`OVERRIDES` contains
> +   “arm”. The “nooverride” specific version is not used because
> +   :term:`OVERRIDES` does not contain “nooverride”.
> 
>     To better understand this, consider a practical example that assumes
>     an OpenEmbedded metadata-based Linux kernel recipe file. The
> @@ -552,7 +560,7 @@ variable.
> 
>        DEPENDS = "glibc ncurses"
>        OVERRIDES = "machine:local"
> -      DEPENDS:append:machine = "libmad"
> +      DEPENDS:append:machine = " libmad"
> 
>     In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".