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

DITA 1.3: Coming soon to an editor near you

The OASIS committee has been working hard at preparing the new release of the DITA specification, DITA 1.3, which is currently planned for Q1 of 2015. In addition to bug fixes and miscellaneous quality improvements, DITA 1.3 will introduce some very interesting features, including:

  • Better support for context-sensitive help
  • A new topic type for troubleshooting
  • Conditional processing enhancements
  • Enhancements to the DITA 1.2 key and keyref feature (scoped keys)
  • New domains for MathML, SVG, and release management
  • Improvements to the Learning and Training domain

My original plan for today was to cover all the new features, but it made for a very long blog post. So instead I’ll go over each important feature in separate posts over the next few weeks. If you’re impatient and want to know the details of the DITA 1.3 specification right now, see the links at the bottom of this post.

Note: Since DITA 1.3 is not released yet, the specification may change and the information and samples in this post may need to be revised.

Let’s start with context-sensitive help.

Better support of context-sensitive help

The current DITA specification is very limited in terms of support provided for context-sensitive help (CSH). DITA 1.3 plans to address the following two limitations:

  • Inability to manage multiple CSH callback IDs from the same DITA source
  • Inability to specify target runtime display from the DITA source

Managing multiple CSH callback IDs from the same DITA source

When generating CSH from DITA, the <resourceid> element can be used to specify the callback ID, which is the hook used to link the DITA topic to the appropriate user interface area. For example, we used the <resourceid> element as follows for the Web Author help:

<prolog>
 <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/>
</prolog>

The problem with DITA 1.2 is that the <resourceid> metadata is limited in the information it can contain to differentiate between multiple target outputs. For example, consider a topic that is used in three different target outputs: Online help, embedded user assistance, and mobile help. If each target application uses its own callback ID scheme, then multiple different context IDs must be specified for the same topic. Since this information cannot be specified in the DITA 1.2 <resourceid> metadata, the mapping between the DITA source topic and the callback IDs must be maintained outside of the DITA files.

To solve this issue, DITA 1.3 adds three new metadata attributes to <resourceid>:

  • appid: Identifies a referenced topic to an external application
  • ux-context-string: Specifies a callback context ID for that topic
  • ux-source-priority: Since the resourceid metadata can be set at the map level or the topic level, this attribute specifies how to resolve conflicts between callbacks defined in a map and in a topic; valid values are map-takes-priority and topic-takes-priority. So if the resourceid information provided in the topic is different from the resourceid provided for that topic in the map, this attribute specifies which resourceid to use.

For example, the following code configures callbacks for two target outputs for the create_image topic: One for the Web Author application and one for the Eclipse Client.

<map title=”DITA CMS Help”>
  <topicref href=”create_image.dita” type=”task”>
    <topicmeta>
      <resourceid
        appname=”cms.webauthor”
        appid=”create_image”
        ux-content-string=”com.ixiasoft.webauthor.help.create_image”
        ux-source-priority=”map-takes-priority”/>
      <resourceid
        appname=”cms.eclipseclient”
        appid=”create_image”
        ux-content-string=”com.ixiasoft.eclipseclient.help.create_image”
        ux-source-priority=”map-takes-priority”/>
    </topicmeta>
  </topicref>
</map>

I’m assuming that the appid attribute in DITA 1.3 is replacing the id attribute in DITA 1.2, since I don’t see why we would need both.

Specifying target runtime display from the DITA source

To provide the details of the target display, DITA 1.3 also adds a new element, <ux-window>, and a new attribute for <resourceid>:

  • <ux-window>:  This element lets you configure a target display profile and include information such as the size of the window, some of its features, etc. For example, the following <ux-window> element configures the display for a mobile environment:
    <topicmeta> 
      <ux-window id=”task_window” name=”mobile_ios” top=”10″ left=”20″ 
       height=”400″ width=”500″ 
       features=”status=yes,toolbar=no,menubar=no,location=no” 
       relative=”true” full-screen=”no”/> 
    </topicmeta>
    
  • You can then specify this profile in the ux-windowref attribute of the resourceid, as shown below:
    <resourceid 
     appname=”cms.webauthor” 
     appid=”cms.webauthor.mobile” 
     ux-content-string=”com.ixiasoft.webauthor.help.create_image″ 
     ux-source-priority=”map-takes-priority” 
     ux-windowref=”mobile_ios”/>
    

I’m not sure yet about this new improvement. One of the strengths of DITA has always been to separate the source content from how it will look in the output. I see this kind of specification as more appropriate in a transformation scenario. But maybe it’s a requirement for mobile environments, and since I haven’t had to produce mobile help yet, I’m not allowed to complain. :)

In the next post, I’ll cover the new topic type for troubleshooting. Should be interesting!


For more information about DITA 1.3:

Share this article:
Facebook Twitter Email Linkedin

Leave a Reply

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