On Tue, 11 Feb 2020, Ross Burton wrote:

Ah gotcha. My docbook-fu is somewhat hazy.

Yes, seems sensible.

Ross

On Tue, 11 Feb 2020 at 14:43, Robert P. J. Day <rpjday@...> wrote:

On Tue, 11 Feb 2020, Ross Burton wrote:

My problem with <firstterm> is that you need to keep on reviewing to
verify it is the first usage. Better to post-process that, surely.

but that's not the way it's normally used ... <firstterm> doesn't
necessarily mean the physically first time a term is used, it's more
typically used to identify where the term is formally introduced and
explained to the reader.

for example, there's nothing wrong with using, say, "BSP layer"
early in a manual as part of a list of YP components or something, but
<firstterm> would be used when the manual finally got around to
explaining the term. that's why <firstterm> is frequently used for
index generation; because that's where the reader should go for the
*explanation* of the term, not just its first physical occurrence.

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.

rday

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:

<literallayout class='monospaced'>
$ bitbake -h
$ bitbake --help
</literallayout>


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.