• 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
  • Support the site
  • Contact
  • Recordings

Best practices for keys

Posted on 12.02.16

Advanced reuse in DITA Lesson 2: Using keys Best practices for keys
Lesson Progress
0% Complete

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
    Need DITA help? We offer flat-rate consulting. Get help.
  • Scriptorium logo
    Already in DITA and need support? Contact us.
RSSTwitter

Want to add content? Join the ditatraining GitHub repository.

  • Home
  • Sponsor
  • News
  • Contact
  • Privacy

Maintained by Scriptorium Publishing

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