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

["Robert P. J. Day" <rpjday@crashcourse.ca>]

  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
========================================================================