with the recent loss of scott rifenbark, since i used to be fairly
active in working on the docs, i figure it's time to get off my a**
and get involved again and contribute. to that end, i once made a
suggestion about being more precise about the docbook markup being
used in the YP manuals.

in many cases, a number of types of entities in the docs are marked
up simply as <filename> which, when generating HTML, renders as
simple italics. so in cases like generating HTML, there's no
difference in whether the entity being marked up is actually a
filename, or a command, or something just being emphasized, and so on.
but when one thinks of generating more refined output (PDF, for
example), it would be useful if those entities really had the
potential to be rendered differently. here are some examples.

first, yes, if something is a filename, then <filename> is the
obvious markup.

on the other hand, variables should properly be marked up as
<variable>, which they currently aren't. a good example is in the
reference manual, the variables, where glossary definitions all use
the <filename> markup for variables. again, it may make no difference
in the ultimate rendering to something as trivial as HTML but, some
day, it will be useful to be able to render things differently
depending on the choice of output.

options should be tagged as <option>, which actually does look nicer
even in HTML output; at the moment, most options are simply quoted, as
in:

To ensure consistent behavior, BitBake's "-r" and "-R" ...

another woefully underused tag is <firstitem>, meant to emphasize
the first time a term is being used to grab the reader's attention.
again, for HTML, that renders simply as italics, but who knows what
might happen in the future. also, using the <firstterm> tag provides a
simple way to collect all such expressions in the docs, perhaps for
index generation.

a final example is command markup, which ideally would use the
<command> tag. i tested that and, in the current doc processing
toolchain, it shows up in HTML as a fairly aggressive bolding. but
even if that seems unsightly, the proper approach would be to use
proper markup, then tweak the stylesheets to define how it *should* be
rendered.

obviously, this is not a high priority as the docs are in great
shape as it is, but i think at some point it would be useful to start
using appropriate markup, and adjust the backend XSL stylesheets to
define the rendering.

thoughts?

rday

--

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

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