Utiliser l’élement <keydef> plutôt que <topicref>
L’élément <keydef> est une spécialisation de <topicref>. Bien que vous pouvez utiliser l’élement <topicref> pour définir une clé, il est recommandé de plutôt utiliser <keyref> pour plusieurs raisons :
- Vous indiquez précisement sur le plan sémantique ce que vous faites
- L’élément <keydef> est automatiquement marqué par l’attribut et la valeur processing-role= »resource-only ». Sans cet attribut, le transformateur ajoutera la rubrique de réutilisation de contenu à la publication, ce que vous ne voulez probablement pas.
- Utiliser l’élément <keyref> vous forcera à utiliser l’attribut keys, ce qui peut vous aider si vous avez tendance à oublier.
Rassembler les clés dans une sous-carte
Il fait partie des bonnes pratiques de rassembler toutes les clés dans une seule sous-carte. Deux arguments viennent soutenir cette idée :
- Une fois que toutes les clés sont rassemblées dans une seule sous-carte, vous et votre équipe peuvent réutiliser cette dernière dans toutes les autres cartes que vous le souhaitez.
- Pour changer la définition de la clé utilisée par une carte, il est simplement question de remplacer une sous-carte contenant les clés par une autre plutôt que mettre à jour tous les éléments <keydef>. De même, vous pouvez ajouter plusieurs éléments <mapref> à votre carte et avoir recours au traitement conditionnel pour exclure les cartes et clés de votre choix.
Ajouter une définition de clé dans une bookmap
La structure de l’élément <bookmap> n’autorise pas <topicref>, <keydef> ou <mapref> comme élément enfant, alors il est difficile de savoir comment définir une clé.
Un nombre considérable d’utilisateurs de DITA placent leurs éléments <keydef> et <mapref> comme éléments enfants de <frontmatter>. Cette pratique assure que ces éléments seront visibles par les utilisateurs éditant la carte.
Contributors
- Simon Bate
- Jake Campbell
- Gretyl Kinsey
- Decarnelle Rémi (traducteur)