Utilisation des clés et des références de clé

L'Arbortext Editor assure la prise en charge des références de clé, comme cela est défini dans la section Key based (indirect) addressing (Adressage (indirect) basé sur les clés) de la spécification DITA Architectural Specification définie par l'organisme OASIS. L'interface utilisateur Arbortext Editor offre de nombreuses fonctionnalités très pratiques pour configurer les définitions de clés dans vos plans DITA et insérer des références de clé dans vos plans et rubriques. En outre, Arbortext Editor propose un plan DITA spécialisé appelé Plan de définition de clés DITA prévu uniquement pour contenir les définitions de clés. Ce plan permet de fournir des informations supplémentaires pour vos définitions de clés.

La solution la plus pratique pour stocker vos définitions de clés est de dédier un plan DITA aux définitions de clés. Il suffit alors d'utiliser un élément mapref pour inclure le plan contenant vos définitions de clés dans un autre plan DITA, s'il y a lieu de le faire. Il est suggéré d'utiliser le plan de définition de clés DITA pour stocker vos définitions de clés.

Les parties suivantes de l'interface utilisateur Arbortext Editor prennent en charge les références de clé :

◦ Rechercher des références de clé : affiche la boîte de dialogue Clés et références de clé en indiquant uniquement les clés présentes dans la balise contenant le curseur.

Une version de cet onglet prévu pour modifier les définitions de clés est disponibles dans la boîte de dialogue Modifier les attributs, dans le plan de document et dans l'affichage en colonnes.

◦ L'option Keyref est disponible dans l'ensemble des onglets et boîtes de dialogue du Gestionnaire de ressources, à l'exception de ceux applicables aux références de contenu. Cette option vous permet de saisir le nom de la clé à insérer dans l'attribut keyref pour la référence en cours de création ou de modification.

◦ L'option Conkeyref est disponible dans l'onglet et la boîte de dialogue du Gestionnaire de ressources destinés aux références de contenu. Cette option vous permet de saisir le nom de la clé à insérer dans l'attribut Conkeyref pour la référence en cours de création ou de modification.

◦ Les onglets et les boîtes de dialogue Lien/Xref, Référence de contenu et Rubrique permettent d'accéder aux plans DITA contenant les définitions de clés et d'utiliser une définition de clé donnée pour la référence insérée ou modifiée.

◦ Ajouter/supprimer un plan : permet d'ajouter ou de supprimer des plans de la liste de plans contenant les définitions de clés destinées à la boîte de dialogue Insérer une référence de clé.

◦ Sélectionner une référence : permet de sélectionner le document à ouvrir lorsqu'un élément source comporte plusieurs cibles de référence définies.

◦ Clés et références de clé : affiche les définitions de clés et les références de clé contenues dans le document actuel et dans les documents référencés à partir du document actuel.

Par défaut, l'interface utilisateur des références de clé de l'Arbortext Editor est disponible dans . Si vous n'utilisez pas de références de clé dans votre documentation DITA, vous pouvez supprimer les fonctionnalités correspondantes de l'interface utilisateur.

La disponibilité de l'interface utilisateur des références de clé dépend du mode de configuration de la préférence avancée ditakeyrefui. Pour supprimer l'interface en question, donnez à cette préférence la valeur off.

Pour trouver les définitions de clés associées aux références de clé, l'Arbortext Editor doit connaître le contexte de clé pour le document actuel. Un contexte de clé est un plan DITA contenant les définitions de clés pertinentes. Si le plan contenant les définitions est un plan de définition de clés DITA, il est possible d'ajouter des informations supplémentaires aux définitions de clés affichées dans l'interface utilisateur des références de clé. Le contexte de clé d'un document est déterminé par les paramètres de l'option ditakeycontext.

L'option ditakeycontext, configurée sur un plan unique, définit le contexte de clé primaire pour le document actuel pendant la session active. Lorsque le contexte de clé est établi pour un document, cela a une incidence sur la façon dont Arbortext Editor gère les références. Si, par exemple, l'attribut href et l'attribut keyref sont tous les deux définis pour une balise d'image, Arbortext Editor affiche l'image en tenant compte de la définition de la clé de l'attribut keyref. Arbortext Editor donne la priorité à une référence de clé ou à une référence de clé de contenu s'il existe un contexte de clé établi contenant une définition de clé correspondante.

L'option ditakeycontext peut être définie de façon explicite ou automatiquement par l'Arbortext Editor dans certains cas. Si, par exemple, vous ouvrez un document en cliquant deux fois sur une référence croisée ou une référence de rubrique, le contexte de clé du document d'origine est appliqué au document en question. De la même manière, lorsque vous ouvrez un document à partir d'une boîte de dialogue DITA de l'Arbortext Editor, le contexte de clé du document actuel est appliqué au document en question. Si le document d'origine est un plan DITA sans contexte de clé, ce plan devient le contexte de clé pour le document ouvert.

Les définitions de clés permettant l'insertion dans un document dépendent d'une autre option, ditakeybaselist. Le principal intérêt de l'option ditakeybaselist est de dresser la liste des plans utilisés pour les définitions de clés affichées dans la boîte de dialogue Insérer une référence de clé et dans l'option Keyref du Gestionnaire de ressources. A la différence de ditakeycontext, ditakeybaselist est une préférence avancée, peut contenir plusieurs plans et persiste d'une session Arbortext Editor à l'autre. Si vous avez attribué une valeur à l'option ditakeybaselist alors que le plan correspondant à l'option ditakeycontext actuelle ne figure pas dans cette liste, le plan du contexte de clé est ajouté en début de liste des plans ditakeybaselist pour la session active.

Arbortext Editor fournit un plan DITA spécialisé appelé Plan de définition de clés DITA. Ce plan, destiné uniquement au stockage des définitions de clés, contient des éléments supplémentaires permettant de compléter les informations de vos définitions de clés. Ces informations complémentaires sont présentées à différents endroits de l'interface utilisateur des références de clé. Le plan de définition des clés DITA figure dans la catégorie DITA Technical Content de la boîte de dialogue Nouveau.

Le plan de définition de clés ajoute d'autres éléments à l'élément topicmeta, ce qui permet de disposer d'informations supplémentaires sur les définitions de clés. Pour tirer parti de ces éléments, il suffirait d'insérer un élément keydef dans le plan, d'incorporer un élément topicmeta dans l'élément keydef et un élément keyinfo dans topicmeta. Vous êtes libre ensuite d'insérer les nouveaux éléments de métadonnées de votre choix dans keyinfo. Vous pouvez également utiliser l'onglet Définition de la clé du Gestionnaire de ressources dans un plan de définition de clés pour ajouter ces informations supplémentaires à vos définitions de clés.

Les éléments supplémentaires suivants, applicables aux références de clé standard, sont disponibles dans topicmeta :

Pour remplacer un contenu via une référence de clé de l'Arbortext Editor, vous pouvez faire appel à l'attribut conkeyref d'un élément pour configurer une référence de clé de contenu. Comme pour les références de clé standard (lorsqu'une référence de clé de contenu est associée à une définition dans le contexte de clé pour un document et que les attributs conref et conkeyref sont définis pour un élément), Arbortext Editor affiche le contenu associé à conkeyref et accorde généralement la priorité à la référence de clé de contenu.

Vous pouvez utiliser une définition de clé standard afin de configurer les clés pour les références de clé de contenu. Toutefois, le plan de définition de clés DITA offre des éléments supplémentaires qui vous aideront à configurer les définitions de clés pour les références de contenu. En outre, pour inclure des références de clé de contenu dans la boîte de dialogue Insérer une référence de clé, vous devez configurer les définitions de clés associées dans un plan de définition de clés DITA : Les éléments supplémentaires suivants s'appliquent aux références de clé de contenu :

L'élément est une spécialisation de l'élément keydef. Les éléments comportant des ID à l'intérieur de rubriques ou de plans faisant référence à un nom de clé défini avec keyconrefs sont affichés sous forme de cibles pour une référence conkeyref dans la boîte de dialogue Insérer une référence de clé. L'attribut scope sur cet élément est défini sur local. L'attribut format a pour valeur dita (valeur par défaut) ou ditamap.

Cet élément inclut également le nouvel élément keyinfo et l'ensemble de ses sous-éléments. Si vous attribuez une valeur à l'élément keysubelementid dans une définition keyconrefs, seuls les éléments possédant cet ID seront applicables à une référence de clé de contenu utilisant cette définition. Sinon, tous les éléments avec ID sont disponibles.

Cet élément fait partie de l'élément keyinfo. Lorsque l'attribut value de l'élément keyforconrefs a pour valeur true (valeur par défaut), cela signifie que cette définition de clé concerne une référence de clé de contenu et qu'elle sera traitée comme tel dans la boîte de dialogue Insérer une référence de clé. Cela vous permet de faire appel à keydef et à d'autres éléments du plan pour configurer des définitions de clés destinées aux références de clé de contenu.

Grâce au plan de définition de clés DITA, il est possible de configurer vos définitions de clés de contenu de façon à disposer d'un seul élément ou de tous les éléments avec ID pour une référence de clé de contenu. Pour qu'un seul élément soit disponible pour une référence conkeyref dans la boîte de dialogue Insérer une référence de clé, vous devez le définir dans un plan de définition de clés DITA à l'aide du balisage suivant :

Par exemple, la définition de clé suivante ajoute l'élément ph avec l'ID custom de la rubrique strings.dita dans la boîte de dialogue Insérer une référence de clé en tant que cible conkeyref :

<keydef keys=”strings” href=”strings.dita”>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>

Pour que tous les éléments possédant des ID soient disponibles dans un plan ou une rubrique pour une référence conkeyref dans la boîte de dialogue Insérer une référence de clé, vous devez également définir ces éléments dans le plan de définition de clés DITA. Vous pouvez définir ce balisage à l'aide des méthodes suivantes :

• Utilisez tout élément valide pour configurer une définition de clé avec un élément keyforconrefs à l'intérieur de l'élément keyinfo dans l'élément topicmeta.

Vous pouvez également utiliser des références de clé standard pour insérer du texte dans vos documents. L'attribut keyref est défini pour la plupart des éléments DITA. Vous pouvez inclure du texte dans vos définitions de clé à insérer dans ces éléments, lorsque l'élément est vide et est associé à un ensemble de références de clé. Pour être utilisé afin d'insérer du texte, l'élément doit être vide. Par exemple, votre document peut contenir les éléments suivants :

La clé référence la définition de clé suivante :

Lorsque vous publiez le document, le texte suivant est inséré dans l'élément ph :

Vous pouvez également inclure un balisage avec le texte à insérer. Par exemple, lorsque la clé référence la définition de clé suivante :

Le texte suivant est inséré dans le document :

Outre l'insertion de texte, vous pouvez aussi transformer des éléments non liens en éléments liens, et vice versa, en incluant l'attribut href dans votre définition de clé. Par exemple, considérons les définitions de clé suivantes :

<keydef keys="product-name" href="acme.dita">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>

Ces définitions de clé sont référencées par les éléments suivants dans votre document :

Lorsque vous publiez le document, le texte suivant est inséré dans celui-ci :

Notez que lorsqu'un attribut href est associé à la définition de clé, l'élément dans lequel le texte est inséré devient un élément lien. Si aucun attribut href n'est associé, même un élément lien tel que xref ne contient pas de lien. Ce comportement de lien s'applique même si l'élément qui référence la définition de clé contient du contenu et ne peut pas être utilisé pour l'insertion de texte. Par exemple, considérons le cas où l'élément suivant référence la définition de clé ci-dessus :

Dans ce cas, la référence de clé transforme l'élément en élément lien et n'insère pas le texte dans la définition de clé lorsque le document est publié.

Le texte à insérer à partir d'une définition de clé est déterminé suivant l'ordre de priorité ci-dessous :

Par exemple, la définition de clé suivante contient du texte dans plusieurs zones destinées à l'insertion de texte :

Dans ce cas, le texte inséré pour la référence de clé correspond au contenu de l'élément keyword, dans la mesure où il est prioritaire sur le contenu de l'attribut navtitle.

Les éléments suivants sont des cas particuliers en ce qui concerne l'insertion de texte :

L'élément link ne contient pas directement de texte. Il comporte des éléments linktext et desc facultatifs qui peuvent contenir du texte. Dans ce cas, si l'élément topicmeta de votre définition de clé inclut les éléments linktext et desc, ces éléments sont insérés dans l'élément link au moment de la publication du document.

L'élément image contient un élément alt qui fournit une description écrite de l'image. Si un élément image vide comporte une référence de clé à une définition de clé contenant du texte pour insertion, ce texte est inséré dans le image en tant qu'élément alt lors de la publication.

Certains éléments DITA, comme longdescref, contiennent l'attribut keyref mais n'autorisent pas le contenu texte. Ces éléments ne peuvent pas être utilisés pour l'insertion de texte au moyen des références de clé.

L'interface utilisateur de Arbortext Editor offre les fonctionnalités suivantes pour prendre en charge l'insertion de texte avec les références de clé :

• La boîte de dialogue Informations sur la référence de clé fournit une option Texte qui affiche le contenu texte, y compris le balisage, inclus dans la définition de clé.

• La boîte de dialogue Insérer une référence de clé affiche le contenu texte pour une définition de clé, y compris le balisage, dans la colonne Ressource.

En outre, lorsque la préférence avancée ditatextkeyrefs est définie sur on, les éléments non liants qui autorisent une référence de clé s'affichent dans liste déroulante Insérer.

• Les éléments vides auxquels est associée une référence de clé affichent le nom de la référence de clé entre parenthèses, lors de la publication d'un document DITA :

Notez que cette fonction est uniquement prise en charge pour les éléments non liens dans les feuilles de style par défaut des documents DITA. Le nom de la référence de clé apparaît uniquement lors de l'édition de documents dans Arbortext Editor. Il n'apparaît pas lors de la publication du document.

Lorsqu'une référence de rubrique contient une référence de clé, certaines des informations de l'élément topicmeta peuvent être incompatibles avec des informations similaires de la définition de clé. L'élément topicref contient un élément topicmeta, comme c'est le cas pour une définition de clé. Les règles suivantes sont appliquées lors de la fusion du contenu topicmeta d'un élément topicrefavec une référence de clé et la définition de clé référencée :