[yocto] the apparent need for docbook <replaceable> tag in manual examples

[Robert P. J. Day]

On Mon, 23 Jun 2014, Christopher Larson wrote:

>
> On Sun, Jun 22, 2014 at 6:20 AM, Robert P. J. Day <rpjday at crashcourse.ca> wrote:
>         as i said, it took me a few minutes to figure out what the
>       conditional metadata example above was trying to demonstrate, but as
>       soon as i saw a real example in the codebase, it was perfectly clear.
>       to this end, i'm creating wiki pages that show stuff like that
>       exactly, like this one for conditional overrides:
>
>
> It's not directly related, but here's some background if it helps
> anyone at all.
>
> Conceptually, when we designed overrides, it was created to let us
> implement layering of metadata (note: not layers as in yocto layers,
> but conceptual layers), to let us always let more specific
> information be used in preference to less specific information.
> Machine information will be used in preference to Architecture which
> is used in preference to the default. This lets us ensure that we're
> always using the most accurate information available about the
> configuration in question.
>
> I've always thought that thinking of it this way helps one see the
> purpose behind the mechanism (and you can see that the order of the
> includes/requires in bitbake.conf essentially implements the same
> ordering where possible, to provide the same capability based on
> load order of the config files). I'm not sure if any of our docs
> talk about it this way, and I'm not sure if it helps anyone else
> wrap their heads around it, but I'm throwing it out there since I've
> found that some folks seem to find it a useful way of looking at it.

  sure, all this makes sense. my main point (at least, i hope my main
point) was that the way OVERRIDES was explained was overly vague and
it took a few minutes of re-reading, then jumping into the codebase
for examples to suddenly twig on what it was doing, which is why i now
like to pull examples out of the codebase for all my explanations.

  i also think it would be a good idea to avoid examples in the
manuals that use generic terms like "foo" and "bar" rather than actual
code snippets that are more obvious, but that's just me.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================