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 ======================================================================== -- _______________________________________________ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto