Skip to contentSkip to conversation

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

PATCH Robert P. J. Day 3 participants 4 messages Jun 22, 2014 – Jun 26, 2014

lore
Share & tools
lore
#0 lore raw

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:

(quoted diff) +0 -0

b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index a9f5072..f8be373 100644

doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +1 -1
@@ -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

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#1 lore raw
Quoted 6 lines · Robert P. J. Day

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.

Signature · 5 lines
Christopher Larson
clarson at kergoth dot com
Founder - BitBake, OpenEmbedded, OpenZaurus
Maintainer - Tslib
Senior Software Engineer, Mentor Graphics
#2 lore raw
Quoted 21 lines · Christopher Larson

On Sun, Jun 22, 2014 at 6:20 AM, Robert P. J. Day <[email protected]> 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.

Quoted 8 lines

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

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#3 lore raw
In reply to Robert P. J. Day
Quoted 6 lines · 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.

Quoted 8 lines

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.

Quoted 54 lines

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:

doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +1 -1
index a9f5072..f8be373 100644
@@ -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