Robert P. J. Day
On Tue, 11 Feb 2020, Ross Burton wrote:
Ah gotcha. My docbook-fu is somewhat hazy.heh ... i remember it took me a few reads once upon a time to
finally grok the proper usage of a lot of docbook markup. in any
event, i'm not pushing for a bunch of stuff to happen all at once, i'm
just going to collect ideas for future work.
first thought (as i whined about already) is to start using at least
a minimal set of more appropriate markup (<variable>, <command>,
<option>, <firstterm> and so on).
following on that, it's inevitable that, even when the markup is
appropriate, the rendering might not be ideal, so start tweaking XSL
stylesheets to change that rendering as needed.
in addition, depending on need, perhaps invent new markup (although
this is pretty extreme given that docbook should support almost every
type of markup imaginable).
finally (and really long term), maybe move to docbook 5 and Relax
NG, but that would be a long way off if it even happens at all.
anyway, i'll just put these ideas aside for now.
p.s. one fairly obvious improvement would be to define the proper
rendering of code or command-line snippets. right now, as i read it,
command examples are marked up with:
$ bitbake -h
$ bitbake --help
which is kind of cumbersome and requires the author to add the proper
leading spaces for rendering. i'm fairly sure XSL can make that
simpler so that arbitrary indentation is processed properly. again, a
long term idea.