I have a question whether markup inside title elements is recommended
practice.
For example, consider text like
You can use commands <command>foo</command> or
<command>bar</command> for this.
Let's say we have a refentry for "foo", so it would be nice to write
You can use commands <xref linkend="foo-refentry"/> or
<command>bar</command> for this.
But then the "foo" link is formatted in normal font not monospace, so
this looks a bit strange.
Now to fix, we could either fix this at the source:
You can use commands <command><xref linkend="foo-refentry"/>
</command> or <command>bar</command> for this.
or at the target, by changing the refentry like
<refmeta>
<refentrytitle><command>foo</command</refentrytitle>
The latter is tempting because you only need to set it once, and you
could even apply different tags for different refentries (command,
function, envar). But it seems there are some dubious side effects in
the rendering, such as seeing the monospace font in the table of
contents, and the man page rendering also puts font markup in places
where it shouldn't be. So maybe this isn't a well-trodden path?
What do people think is the soundest way to handle this?
I'm thinking maybe adding a role attribute to the refentrytitles and
then customizing the xref templates somehow.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
