OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: using markup inside title elements


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.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]