Profiling a piece of content and making it conditional is a popular way to handle content variations. It was known well before DITA was born. If you were using tools, like FrameMaker or RoboHelp, chances are you used conditional tags too.

There is one problem with conditional content, though. As the amount of parameters by which you are profiling grows, the complexity of conditional content grows too. Let’s say that you are profiling content by products. When you started, there were just three major products so maintaining three conditional tags wasn’t a big deal.

But as your company kept moving on, more and more products were released. Perhaps, each product has a series of flavors too. For example, I used to see companies whose products have variations depending on the geographic market where they are sold because of local regulations and market specifics. Now, instead of having 3 conditional tags, you have to keep multiple tags and maintain even more variations.

If you are using different colors for different conditions, your content now looks like a rainbow. It’s very hard to read and understand which piece of content will appear in a particular output. Because you might conditionalize not just by products, but for example, by audiences and OEM partners too, the situation becomes even more complicated.

A good news is that in DITA, conditional content is not the only way to handle content variations. In this post, I’m going to show you how you can use the key reference mechanism to swap between product images.

Imagine that you are working for a company that manufacturers printers. The company offers three models:

  • EasyPrint Basic, which can just print
  • EasyPrint Pro, which can print and scan
  • EasyPrint All-In-One, which can print, scan, send and receive faxes, and copy

You have a topic in which you provide the overview of the product. 80% of the content is the same for all the models. However, the image of the product is model-specific and should be changed depending on the output you want to generate. Using the conditional content mechanism, you would do probably something like this:


<fig product=”Basic”>

      <image href=”../graphics/printer_basic.png” />


<fig product=”Pro”>

      <image href=”../graphics/printer_pro.png” />


<fig product=”All-In-One”>

      <image href=”../graphics/printer_allinone.png” />



The key reference mechanism lets you refer to the image by a key reference. Key is an alias with a reasonable name rather than a specific location of the image file. For example:


<fig product=”Basic”>

      <image keyref =”Product_Image” />



In the map, you resolve the key “Product_Image” to the actual file name, depending on the output you want to generate. If you have a separate map per product, then you specify the location of the product image file differently in each map:





<title>EasyPrint Basic User Guide</title>

      <keydef href=”graphics/printer_basic.png ” format=”png” keys=”Product_Image“/>

      <topicref href=”topics/overview.dita”/>




<title>EasyPrint Pro User Guide</title>

      <keydef href=”graphics/printer_pro.png ” format=”png” keys=”Product_Image“/>

      <topicref href=”topics/overview.dita”/>




<title>EasyPrint All-In-One User Guide</title>

      <keydef href=”graphics/printer_allinone.png” format=”png” keys=”Product_Image“/>

      <topicref href=”topics/overview.dita”/>


By the way, using the same approach, you can swap between low resolution and high resolution images. You add a single <image> using a key reference, and resolve the key reference to the file name of the either high resolution or low resolution image depending on your output needs.

In the next post, we’ll talk about how to use the content key reference (conkeyref) mechanism to swap between product-specific pieces of content, like steps in a procedure.

Leave a Reply

Your email address will not be published. Required fields are marked *