7.5. xref

Utilisez l'élément de référence croisée (<xref>) pour lier à un emplacement différent dans le thème courant, ou à un thème différent dans le même système d'aide, ou à des ressources externes, telles que des pages web, ou à un emplacement dans un autre thème. L'attribut href sur l'élément <xref> donne l'emplacement de la cible.

En général, il est préférable de se limiter aux liaisons vers des thèmes de référence où le contenu de la cible transparaît clairement du texte de <xref>, par exemple des noms d'interface (API) et leurs descriptions. Avec d'autres types d'information, il ne sera peut-être pas aussi clair pour l'utilisateur s'il doit suivre le lien, ce que souvent il fera, manquant ainsi des informations importantes dans les paragraphes suivants. À chaque fois que possible, il sera donc judicieux de réserver les liens à la fin du thème, dans l'élément <related-links>, plutôt que de réaliser une liaison depuis le contenu du corps en utilisant l'élément <xref>. On peut aussi gérer les liens à la fin d'un thème depuis l'extérieur du thème, avec des cartes DITA : cela permet d'intégrer rapidement les thèmes dans de nouveaux contextes sans rompre les liens.

Exemples

Voici une exemple de référence croisée vers un autre thème ; le titre de ce thème servira de texte au lien :

<p>Background information about DITA is provided in the topic titled
<xref href="whatsdita.dita#tmmdita"></xref>.</p>

Voici un exemple de référence croisée vers un autre thème ; le texte fourni servira de texte au lien :

<p><xref href="whatsdita.dita#tmmdita">Background information about DITA</xref>
is provided free of charge.</p>

Si vous faites une liaison vers quelque chose au sein d'un thème, vous devriez employer le format suivant dans l'attribut href :

filename.xml#topicid/elementid

Si vous faites une liaison au sein du même fichier, vous pouvez abandonner la partie « filename.xml ». Donc, pour une section avec l'identificateur « mysection », vous devriez employer :

#topicid/mysection

Pour un élément de liste dans cette section, en supposant que l'élément a pour identificateur « mylist », utilisez :

#topicid/mylist

Indépendamment de la profondeur d'imbrication de l'élément cible, les seules pièces importantes sont l'identificateur du thème conteneur et l'identificateur de l'élément cible. Les identificateurs de thème dans DITA doivent être uniques au sein d'un fichier, mais les identificateurs des autres éléments ne doivent l'être qu'au sein du thème. On doit s'assurer que l'identificateur du thème fait partie de ses références.

Si une adresse URL contient un caractère ESPERLUETTE « & », il faut le coder à l'aide d'un symbole. Par exemple, pour cette adresse-ci :

http://www.ibm.com/docview.wss?rs=757&context=SSVNX5

Il faut saisir le symbole « &amp; » dans l'attribut href ainsi :

<xref href="http://www.ibm.com/docview.wss?rs=757&amp;context=SSVNX5">
Part number SSVNX5</xref>

Contient :

Doctype Modèle de contenu
ditabase, topic, task, reference, concept ( données textuelles ou ph ou codeph ou synph ou filepath ou msgph ou userinput ou systemoutput ou b ou u ou i ou tt ou sup ou sub ou uicontrol ou menucascade ou term ou q ou boolean ou state ou keyword ou option ou parmname ou apiname ou cmdname ou msgnum ou varname ou wintitle ou tm ou image ou data ou data-about ou foreign ou unknown ou desc) (un nombre quelconque)
map, bookmap ( données textuelles ou ph ou term ou q ou boolean ou state ou keyword ou tm ou image ou data ou data-about ou foreign ou unknown ou desc) (un nombre quelconque)

Contenu par :

Doctype Parents
bookmap desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, organizationname
map desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry
ditabase desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, glossdef, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
topic desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
task desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
concept desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
reference desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
glossary desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, glossdef, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area

Héritage :

- topic/xref

Attributs :

Nom Description Type de donnée Valeur par défaut Obligatoire ?
href Un hyperlien vers une page web externe (URL) ou une autre ressource non-DITA, vers un autre thème DITA dans le même fichier ou un autre, ou vers un élément spécifique dans un thème DITA. L'attribut format identifie le format de la cible. Les cibles non-DITA utilisent une syntaxe URL standard. Le contenu DITA est désigné comme suit :

Cible ailleurs dans le même fichier

  href="#topicID"
  href="#topicID/elemID

Cible dans un fichier différent

  href="filename.dita#topicID"
  href="fname.dita#topicID/elemID"

L'emplacement des éléments dans un thème doit être visible pour l'identificateur du thème conteneur. Seuls l'identificateur de l'élément cible et le thème qui le contient importent : les identificateurs des autres éléments conteneurs (par exemple, un identificateur sur l'élément <body>) ne font pas partie de la syntaxe du lien.

Si l'adresse URL contient un caractères ESPERLUETTE « & », on devra utiliser son symbole (&amp;) pour indiquer ce caractère.

CDATA #IMPLIED non
type Décrit la cible d'une référence croisée. Cf. la section 25.10.2. L'attribut type pour des informations détaillées sur les valeurs gérées et les implications de traitement. CDATA #IMPLIED (traité comme si la cible était de type "topic", ou hérité d'un ancêtre) non
format L'attribut format identifie le format de la ressource référencée. Cf. la section 25.10.3. L'attribut format pour des détails sur les valeurs gérées. CDATA #IMPLIED non
scope L'attribut scope identife l'étroitesse de la relation entre le document courant et la ressource cible.
  • Mettez scope="local" si la ressource fait partie de l'ensemble de contenu courant ;
  • Mettez scope="peer" si la ressource fait partie de l'ensemble de contenu courant mais n'est pas accessible lors de la construction ;
  • Mettez scope="external" si la ressource ne fait pas partie de l'ensemble d'information courant et devrait s'ouvrir dans une nouvelle fenêtre de navigateur ;
  • Cf. la section 25.10.1.1. Utilisation de la valeur "-dita-use-conref-target" pour plus d'informations sur la valeur "-dita-use-conref-target".
La valeur de traitement par défaut est "local". Si aucune valeur n'est spécifiée, mais que l'attribut est défini sur un ancêtre dans une carte ou dans la section <related-links>, la valeur sera héritée de l'ancêtre le plus proche.
(local | peer | external | -dita-use-conref-target) #IMPLIED non
%univ-atts; (%select-atts;, %id-atts;, %localization-atts;) Un ensemble d'attributs liés, décrit à la section 25.7. %univ-atts; entité paramètre sans objet pour une entité paramètre sans objet
%global-atts; (xtrf, xtrc) Un ensemble d'attributs liés, décrit à la section 25.2. %global-atts; entité paramètre sans objet pour une entité paramètre sans objet
class, outputclass, keyref Attributs communs, décrit à la section 25.9. Autres attributs DITA communs