Références croisées et typographie dans les éléments shortdesc

Bien qu'il soit possible d'imbriquer un élément phrase (ph) dans une shortdesc, puis d'inclure le formatage et les éléments xref dans cette phrase, ce n'est pas sémantiquement correct.

À première vue, l'élément shortdesc semble ne pas pouvoir contenir du balisage en ligne tel que des références croisées. En l'examinant de plus près, il devient évident qu'un élément en ligne ph peut être inséré, et que cet élément ph peut contenir des références croisées.

Même si le langage DITA permet techniquement ce type de construction, l'usage ne les préconise pas.

Exemple de code invalide :
<shortdesc>The <xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref> uses...
Exemple de code techniquement valide, mais déconseillé :
<shortdesc>The <ph><xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref></ph> uses...

L'élément shortdesc est destiné à contenir un bref résumé du contenu de la rubrique, et n'est pas nécessairement destiné à être publié avec contenu de la rubrique. Il est destiné aux aperçus de liens et aux info-bulles. Inclure des références croisées dans l'élement shortdesc n'a donc pas de sens.

De la même façon, les éléments typographiques tels que le gras (b) et l'italique (i) ne sont généralement pas appropriés dans les descriptions courtes, même s'ils sont techniquement valides, car les descriptions courtes sont souvent publiées sous la forme d'un texte simple (comme dans les infobulles). Si vous pensez avoir besoin d'une telle mise en forme, vous devez voir si le contenu que vous incluez appartient vraiment à un élément shortdesc.

La shortdesc doit être traitée en tant que métadonnée, non en tant que contenu.

Une shortdesc peut, de façon légitime, avoir besoin de balisage en ligne, comme lorsqu'un indice ou un exposant est nécessaire. Par exemple, une shortdesc peut présenter l'eau comme H<sub>2</sub>O. Cela entraîne inévitablement un problème lorsque le texte de la shortdesc est utilisé dans un contexte où les indices ne sont pas autorisés, comme dans une infobulle ou un titre de rubrique HTML.

Par conséquent, le balisage en ligne dans une shortdesc doit être évité lorsque la mise en forme de ce balisage dans la sortie est importante pour sa signification.