the apparent need for docbook <replaceable> tag in manual examples
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
========================================================================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
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
========================================================================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@@ -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