To boldly go where no tech writer has gone before (one can dream, right?)

Using variables in DITA

While DITA doesn’t provide a dedicated variable mechanism like the one in FrameMaker, variables can be easily implemented in DITA using keydefs, keyrefs, and keywords.

There are a few different ways to create variables in a DITA document; this is the method that we use at IXIASOFT. It requires a basic knowledge of keyrefs; the DITA 1.2 feature article on Keyref overview is the best article I’ve read on the subject.

Our approach is to create a map that is dedicated to defining keys for information that varies per project but that has the same value throughout the document, such as product name, product version, book names, etc. This map is then referenced from any other map that needs to access this information.

To use variables in DITA:

  1. Create a map that will contain the variable definitions.
    For example, I’ve stored my variables in a map called Product_A_variables.ditamap.
  2. In the map, set your variables using the <keydef> element, as shown below:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <map>
    <title>ACME Product A Variables</title>
    <keydef keys="Product_Name">
       <topicmeta>
          <keywords>
             <keyword>ACME Mobile</keyword>
          </keywords>
       </topicmeta>
    </keydef>
    <keydef keys="Product_Version">
       <topicmeta>
          <keywords>
             <keyword>1.0</keyword>
          </keywords>
       </topicmeta>
    </keydef>
    
  3. Add your variables map to your main map:
    <mapref href="Product_A_variables.ditamap" format="ditamap"/>
    
  4. In your documents, specify the variable using the <keyword> element, as shown in the example below:
    <li>To install version <keyword keyref="Product_Version"/> of <keyword 
    keyref="Product_Name"/>, follow this procedure:</li>
    

Et voilà! You could also specify your keydefs directly in your map, but isolating them in another map makes it easy to reuse the information.

Share this article:
Facebook Twitter Email Linkedin

18 Responses to “Using variables in DITA”

  1. Very useful – many thanks for finding and publishing!

  2. Nathalie says:

    I’m glad it’s useful! :) It’s the post that receives the most hits! :)

  3. GottaLoveXML says:

    Excellent. Thank you.

  4. Tom Johnson says:

    Thanks for writing this post. Your explanation was clear and helpful! Keep it up.

  5. Ronny says:

    Awesome
    Thanks, for making this easy to understand.

  6. John says:

    Great concise summary, many thanks! Just starting off with DITA and this was a major issue for us, so it is great to get this kind of advice from an experienced professional.

  7. Thanks, that makes perfect sense. That was exactly what I wanted to know.

  8. Doug says:

    What are the pros and cons of using the method you describe rather than by associating a resource (file) to the dita bookmap that contains definitions of ‘variable’ text?

    The use case I have in mind is one in which the resource associated with the dita bookmap has ‘variables’ that are defined using the DITA element (see the example below). Each ‘variable’ has an ID (“Product_Name” in the example), and a value (“ACME Mobile” in the example). The text that is the value is rendered in the output of the dita map.

    ACME Mobile

    • Nathalie says:

      Hi Doug,

      WordPress is not very good with handling code in comments… Can you please email me your sample code so that I can better answer your question? Try nathlaroche at gmail dot com.

  9. Jeff says:

    Hi Nathalie,

    Do you have any idea of how the OT decides which keyref to use when there are multiple matches?

    I currently use conrefs and a form of xslt substitution to swap conref targets at the moment of publication, which means that when I publish without parameters my documents simply default to the targets that are hardcoded into the topics. Using keyrefs means that I need either filter out all conflicting keyrefs or understand how the OT resolves conflicts.

    I’ve set up a test publication and the behavior does not appear to depend on the position of the conflicting keyref-bearing ditamaps in the main ditamap, or on the values of keyrefs themselves. I’m a little puzzled here.

    Cheers,
    Jeff.

    • Nathalie says:

      Hi Jeff,

      That’s a tricky one. It’s the first definition that the processor finds when going through the map, but it’s not always easy to predict. There’s a very detailed article from the DITA committee that discusses this:
      http://dita.xml.org/resource/dita-tc-faq-about-keys

      But! DITA 1.3 (coming out very soon!) will introduce the concept of key scopes, which I think might be what you need. Key scopes will allow you to specify different definitions for the same key in a map. A new attribute, keyscope, will define a “space” inside which a key will have a specific value, and multiple spaces can be defined in the map. So maybe you won’t need the XSLT substitution when this feature is available? You can find a presentation about keyscopes here:

      http://www.slideshare.net/IXIASOFT/key-scopes-in-dita-13

      Please let me know if I did not understand your question or if this is not what you were looking for. Thanks for your comment! :)

  10. Debbie says:

    I see interesting posts here. Your blog can go viral easily, i
    know sneaky way to get massive traffic from social sites.
    For more info search google for: fejlando’s tips

  11. Nikolaos Giannelos says:

    The exposition of keydef and keyref is very clear, however I find the title misleading, because these are not variables, but CONSTANTS within the map.

    This mechanism simply defines a constant at the map level, just like you would define a constant in, say, the C programming language using the #define directive.

  12. Harri Mehtälä says:

    Does this work in the bookmap as well? I’m having trouble with keywords in FrameMaker. They aren’t showing up.

    Where should I insert the

    in a bookmap?

    I’m not entirely sure if this is causing the problem.

  13. Harri Mehtälä says:

    I of course mean this mapref:

    mapref href=”Product_A_variables.ditamap” format=”ditamap”/

    brackets are removed

  14. Luca says:

    HI, nice post but i’ve a question about my particular case.

    I need a variable that assumes 2 different values within a certain topic, called 2 times within the same map.

    For example: the first time we meet that topic, inside it we find the variable “sensor1” B13028.
    the second time we meet the same topic inside the map, we will find the variable “sensor1” B13001.

    How can i have this?? If I use the structure you describe in this article I get a PDF in which all the “sensor1” are the same, the first I declare.

    is it possible starting from the same topic with a variable to obtain as a result 2 different topic inside the same map?

    I hope i was clear :)

    thank you so much!

Leave a Reply

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