[yocto] standards for YP documentation markup?

[Robert P. J. Day]

  more nitpicky pedantry ... i mentioned this once upon a long time
ago, but i thought i'd revisit it. there is a fair bit of
inconsistency in the docbook markup in the YP docs such that, even
though the end-product looks reasonable, the markup kind of bounces
around all over the place and, in future, would cause all sorts of
hilarity if one wanted to redefine the rendering.

  for instance, there are a number of terms that are apparently
supposed to be rendered in italics at the moment, such as filenames,
variable names, command names and so on. but even though docbook
supports explicit markup using:

  <filename>
  <varname>
  <command>

and so on, if you check the BSP guide, <filename> is being used all
over the place for all of the above; examples:

You use the <filename>yocto-bsp create</filename> sub-command to create
<filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and

and so on. sure, it all looks good right now, but if someone wanted to
make a trivial change to the rendering of, say, just commands, well,
oh dear ...

  other nitpickery i noticed in that same doc is inconsistency of
defining notes depending on whether they have more than one paragraph.
if there's just one para, it's very common to see:

  <note>
    blah blah
    woof woof
  </note>

OTOH, if it's a multi-para note, you see:

  <note>
    <para>
      ... para 1 ...
    </para>
    <para>
      ... para 2 ...
    </para>
  </note>

but look closely at the final rendering and you'll see that the use of
<para> clearly changes the final rendering in terms of line spacing.
and, occasionally, even a single-para note in the guide uses
<para></para> so it's not even consistently inconsistent. :-)

  anyway, yes, it's all picky, but it would be useful to have a short
guide on standard for YP docs markup so that, if someone starts a new
one, it can at least follow some guidelines.

  thoughts?

rday

-- 

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

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