Re: reviving an old suggestion about YP docs markup


Ross Burton <ross@...>
 

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.

rday

Join yocto@lists.yoctoproject.org to automatically receive all group messages.