• 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

Using keys for text

Posted on 12.02.16

Advanced reuse in DITA Lesson 2: Using keys Using keys for text

 

You can use a key as a variable for replaceable text in your DITA topics. Typical uses of keys for text variables include:

  • Product names
  • Product numbers
  • Company names
  • Telephone numbers
  • Titles of other books in a document set

Although there is no limit on the length of the string defined by a key, strings in keys are usually fairly short.

Note: The previous course (Introduction to reuse in DITA) pointed out that it was not a good idea to use replaceable text in anything smaller than a sentence. Overall, this is good advice. However, if you are using keys for a company or product name, particularly when documenting a product that might be rebranded or OEMed, the convenience and consistency provided by keys may outweigh some considerations of localization.

To define a key that will contain a text string, use the keys attribute to name the key, then nest a <topicmeta> element containing a keyword definition inside the <keydef> element. For example:

<keydef keys="product_name">
   <topicmeta>
      <keywords>
         <keyword>Duck Database</keyword>
      </keywords>
   </topicmeta>
</keydef>

This syntax is quite verbose. The good thing is: you define it once, then forget about it.

Note that the string is limited to the content that is allowed in the <keyword> element, that is: plain text, the <text> element, and the <tm> (trademark) element. You cannot use other elements in the string to provide inline formatting or cross-references. If you need additional elements within the string, consider using a conref instead.

Using the key

To use a key for a text string, use the keyref attribute with these elements (or any element specialized from these elements):

  • <ph>
  • <term>
  • <keyword>

This example shows how a key can be used with a <ph> (phrase) element:

Congratulations on purchasing <ph keyref="product_name"/>!

When the DITA map includes the <keydef> element shown above, the output would contain:

   Congratulations on purchasing Duck Database!

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

sidebar

Blog Sidebar

  • Scriptorium logo
    Maximize the value of your content. Read more.
  • 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-2022 Scriptorium Publishing. Content based on the open-source DITA training project.