Cross-references and typography in shortdesc elements

Although it is possible to embed a phrase (ph) element in a shortdesc, and then include formatting and xref elements within the phrase, it is not a semantically sound practice.

At first glance, the shortdesc element seems unable to contain some inline mark-up such as cross-references. On closer examination, it becomes apparent that a ph inline element can be inserted, and that ph element can contain cross-references.

Although the DITA language technically permits this sort of mark-up construct, hacks such as this should not be used.

Example of invalid code:
<shortdesc>The <xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref> uses...
Example of technically valid, but unwise, code:
<shortdesc>The <ph><xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref></ph> uses...

The shortdesc element is intended to contain a brief synopsis of the content of the topic, and isn't necessarily intended to be output as part of the topic content. It is intended for link previews and hover text; it doesn't make sense to include cross-references in these.

In the same way, typographical elements such as bold (b) and italic (i) are not usually appropriate in short descriptions, even though they are technically valid, because short descriptions are often rendered in plain text forms (such as in tooltips). If you think you need such formatting, you should consider whether the content you are including really belongs in a shortdesc element.

The shortdesc should be treated as metadata, not content.

A shortdesc may legitimately need some inline mark-up, such as where a superscript or subscript character is needed. For example, a shortdec might discuss water as H<sub>2</sub>O. This will inevitably present a problem when the shortdesc text is used in a context where subscripts are not permitted, such as in a tooltip or an HTML topic title.

Inline mark-up in a shortdesc should therefore be avoided where the formatting of that mark-up in the output is important to its meaning.