On Tue, 11 Feb 2020, Ross Burton wrote:

On Tue, 11 Feb 2020 at 11:13, rpjday@...
<rpjday@...> wrote:

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.

I'd say fine, patches welcome. Maybe Scott chose a subset of Docbook
to ease the formatting? Either way, I can't see a good argument
*against* using a broader set of tags. At some point you could have
some lint tooling to verify that every <variable> is in the variable
index, for example.

yes, that's along the lines of using <firstterm> when appropriate.
i'm not suggesting trying to dig into every corner of docbook, just
the judicious usage of the most obvious tags. i'll do some research to
see what minimum set of tags would make sense. as a start, probably:

* <filename>
* <variable>
* <command>
* <option>
* <firstterm>

all strike me as obvious (in addition to what's already used).

rday