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

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

[Robert P. J. Day]

  something poor scott rifenbark can ponder in his copious free time
:-), but i think some of the current examples in the various manuals
need to be enhanced with the use of the docbook <replaceable> tag to
emphasize that they are generic references meant to be replaced by
specific values; otherwise, there's potential confusion.

  as a concrete example, i remember *way* back when i was reading
about conditional metadata in the bitbake user manual, particularly
this verbatim example:

  OVERRIDES = "architecture:os:machine"
  TEST = "default"
  TEST_os = "osspecific"
  TEST_nooverride = "othercondvalue"

  because all of the above is currently rendered in the same (courier)
font in the generated manual, i mistakenly thought that all of the
above was to somehow be typed exactly that way, and i was completely
baffled as to what the qualifiers "_os" and "_nooverride" would do. it
was only after searching for examples in the codebase that it dawned
that those strings were meant to be replaced by actual examples of the
current architecture, os, machine and so on.

  duh.

  this can be made more obvious fairly simply with the following
tweak of using the docbook <replaceable> tag:

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index a9f5072..f8be373 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -359,7 +359,7 @@
                         version.
                         Here is an example:
                         <literallayout class='monospaced'>
-     OVERRIDES = "architecture:os:machine"
+     OVERRIDES = "<replaceable>architecture</replaceable>:<replaceable>os</replaceable>:<replaceable>machine</replaceable>"
      TEST = "default"
      TEST_os = "osspecific"
      TEST_nooverride = "othercondvalue"

i've confirmed that that tag is processed properly within a
<literallayout>, and renders in italicized courier font, which is the
visual clue that it's not meant to be read literally.

  oh, and one more related point ... i think it would be more useful
to replace generic manual examples that use meaningless phrases such
as "foo" and "bar" with specific examples yanked from the actual OE
codebase.

  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:

http://www.crashcourse.ca/wiki/index.php/BitBake_Overrides

so rather than try to explain the generic concept, i can just bring up
the wiki page and say, "see? that's how it works." and everyone
understands immediately.

  anyway, just my $0.02. back to work ...

rday

-- 

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

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

Re: the apparent need for docbook <replaceable> tag in manual examples

[Christopher Larson]

[-- Attachment #1: Type: text/plain, Size: 1702 bytes --]

On Sun, Jun 22, 2014 at 6:20 AM, Robert P. J. Day <rpjday@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.
-- 
Christopher Larson
clarson at kergoth dot com
Founder - BitBake, OpenEmbedded, OpenZaurus
Maintainer - Tslib
Senior Software Engineer, Mentor Graphics

[-- Attachment #2: Type: text/html, Size: 2236 bytes --]

Re: the apparent need for docbook <replaceable> tag in manual examples

[Robert P. J. Day]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 2649 bytes --]

On Mon, 23 Jun 2014, Christopher Larson wrote:

>
> On Sun, Jun 22, 2014 at 6:20 AM, Robert P. J. Day <rpjday@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
========================================================================

Re: the apparent need for docbook <replaceable> tag in manual examples

[Rifenbark, Scott M]

On 6/22/2014 6:20 AM, Robert P. J. Day wrote:
>    something poor scott rifenbark can ponder in his copious free time
> :-), but i think some of the current examples in the various manuals
> need to be enhanced with the use of the docbook <replaceable> tag to
> emphasize that they are generic references meant to be replaced by
> specific values; otherwise, there's potential confusion.
>
>    as a concrete example, i remember *way* back when i was reading
> about conditional metadata in the bitbake user manual, particularly
> this verbatim example:
>
>    OVERRIDES = "architecture:os:machine"
>    TEST = "default"
>    TEST_os = "osspecific"
>    TEST_nooverride = "othercondvalue"

Yes - I will put this on my list of things to get done over time. Thanks 
for bringing it up.

>
>    because all of the above is currently rendered in the same (courier)
> font in the generated manual, i mistakenly thought that all of the
> above was to somehow be typed exactly that way, and i was completely
> baffled as to what the qualifiers "_os" and "_nooverride" would do. it
> was only after searching for examples in the codebase that it dawned
> that those strings were meant to be replaced by actual examples of the
> current architecture, os, machine and so on.
>
>    duh.
>
>    this can be made more obvious fairly simply with the following
> tweak of using the docbook <replaceable> tag:
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> index a9f5072..f8be373 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> @@ -359,7 +359,7 @@
>                           version.
>                           Here is an example:
>                           <literallayout class='monospaced'>
> -     OVERRIDES = "architecture:os:machine"
> +     OVERRIDES = "<replaceable>architecture</replaceable>:<replaceable>os</replaceable>:<replaceable>machine</replaceable>"
>        TEST = "default"
>        TEST_os = "osspecific"
>        TEST_nooverride = "othercondvalue"
>
> i've confirmed that that tag is processed properly within a
> <literallayout>, and renders in italicized courier font, which is the
> visual clue that it's not meant to be read literally.
>
>    oh, and one more related point ... i think it would be more useful
> to replace generic manual examples that use meaningless phrases such
> as "foo" and "bar" with specific examples yanked from the actual OE
> codebase.
>
>    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:
>
> http://www.crashcourse.ca/wiki/index.php/BitBake_Overrides
>
> so rather than try to explain the generic concept, i can just bring up
> the wiki page and say, "see? that's how it works." and everyone
> understands immediately.
>
>    anyway, just my $0.02. back to work ...
>
> rday
>