• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Learning DITA

Free DITA training

Free DITA training

  • Log in
  • Register
  • Newsletter
  • Profile
  • Privacy
  • Home
  • About
  • Courses
  • News
  • Resources
    • Recordings
  • Questions?
  • Contact

Best practices for keys

Posted on 12.02.16

Advanced reuse in DITA Lesson 2: Using keys Best practices for keys

Use the <keydef> element, rather than <topicref>

The <keydef> element is a specialization of the <topicref> element. Although you can use the <topicref> element to define keys, it’s better to use <keydef> because:

  • It indicates specifically what you’re doing (semantics).
  • It automatically specifies processing-role=”resource-only”. Without this attribute, the output generator uses the referenced topic exactly where it occurs in the map, which is probably not what you want.
  • It requires you to use the keys attribute (which helps if you tend to forget things like that).

Gather keys in submaps

It’s a good idea to gather all related keys together in a submap. There are two main reasons for doing this:

  • Once you have gathered all related key definitions together in a single submap, you (and others on your team) can reuse that submap in maps or bookmaps for other output targets
  • To change the key definitions used by the map or bookmap, it’s just a matter of switching out one key submap for another (rather than having to update all the keydef elements). Additionally, you can add multiple <mapref> elements to the map or bookmap and use DITA conditional filtering (as described in the first lesson of this course) to hide all but one of the <mapref> elements.

Adding key definitions to bookmaps

The structure of the <bookmap> element does not allow <topicref>, <keydef>, or <mapref> elements as children of the <bookmap> element, so there is no obvious place in a <bookmap> element to place your key definitions.

A number of DITA users place <keydef> or <mapref> elements as children of the <frontmatter> element. This ensures that they are immediately visible to people editing the bookmap.

Contributors
  • Simon Bate
  • Jake Campbell
  • Gretyl Kinsey
Previous Topic
Back to Lesson
Next Lesson

sidebar

Blog Sidebar

  • Scriptorium logo
    Maximize the value of your content. Read more.
  • Scriptorium logo
    Already in DITA and need support? Contact us.
RSSLinkedin

Want to add content? Join the ditatraining GitHub repository.

  • Home
  • News
  • Contact
  • Privacy
  • Cookie Policy

Maintained by Scriptorium Publishing

Logo and site presentation © 2015–2023 Scriptorium Publishing. Content based on the open-source DITA training project.

Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}
Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}