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

["Rifenbark, Scott M" <scott.m.rifenbark@linux.intel.com>]

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
>