Wednesday, September 02, 2015

DITA 1.3 Branch Filtering - Next Generation of Reuse

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Thanks to the hard working OASIS DITA TC Group the DITA 1.3 standard is quite close to being released. Oxygen 17.1 which will be released probably in September this year will have experimental DITA 1.3 support. This will include publishing using a custom build of the latest DITA Open Toolkit 2.x engine in which the main developer Jarno Elovirta has already added incipient support for key scopes and branch filtering.

In this blog post I'm going to give you a small example of how branch filtering can benefit two cases of reuse which could not be done previously. You can read more about branch filtering in the DITA 1.3 specs.

Case 1 - Combine Two Profiles in the Same Publication

Let's say you have a DITA Project about preparing and cooking vegetables. And your DITA Map looks like this:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
 <title>Cooking vegetables</title>
 <topicref href="cleaningTableArea.dita" audience="novice"/>
 <topicref href="preparingVegetables.dita"/>
 <topicref href="addingExtraFlavor.dita" audience="expert"/>
 </map>
You have some content common both for expert and novice users but you also have content which is specific for a target audience. You do not need to teach expert chefs how to clean the table and you do not want to teach novice cooks about enhanced flavoring techniques.
All is fine until at some point you decide to produce a publication which contains merged inside both the novice and the expert map contents. And here's where branch filtering comes for help. You can create a main DITA Map which reuses your current DITA Map with two profiling contexts:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
 <title>Cooking Vegetables.</title>
 <topichead navtitle="Cooking for Beginners" keyscope="novice">
  <topicref href="vegetables.ditamap" format="ditamap">
   <ditavalref href="novice.ditaval"/>
  </topicref>
 </topichead>
 
 <topichead navtitle="Cooking for Experts" keyscope="expert">
  <topicref href="vegetables.ditamap" format="ditamap">
   <ditavalref href="expert.ditaval"/>
  </topicref>
 </topichead>
</map>

Case 2 - Reusing Common Topics with Different Product Names

Let's say you have a simple DITA task in which you have described how a certain task can be performed for a certain product. In our case, the task describes peeling potatoes:

The task works and at some point in your Vegetables Soup publication you realise you need to write a similar task about peeling cucumbers. The task is exactly the same, except the product name. So naturally you want to reuse the existing written task. For this we re-write the task so that instead of of the product potatoes it contains two consecutive profiled product names:
Peeling <ph product="potatoes">potatoes</ph><ph product="cucumbers">cucumbers</ph>
and include the task in the main DITA Map in two places with different ditaval filters applied:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
 <title>Peeling Vegetables.</title>
 <topichead navtitle="Potatoes">
  <topicref href="peeling.dita">
   <ditavalref href="potatoes.ditaval"/>
  </topicref>
 </topichead>
 
 <topichead navtitle="Cucumbers">
  <topicref href="peeling.dita">
   <ditavalref href="cucumbers.ditaval"/>
  </topicref>
 </topichead>
</map>

This kind of usage will produce in the HTML output folder two topic HTML files from the single peeling.dita, one for each filter context.

The DITA samples for this post can be downloaded from http://www.oxygenxml.com/forum/files/branchFilteringBlogSamples.zip.

As usual any feedback is welcomed.

If you would like to beta test Oxygen XML Editor 17.1 with experimental DITA 1.3 support please contact us: support@oxygenxml.com.

5 comments:

  1. This is a really great feature.
    However, any advice on using keydef files on top of that, and how to use them ?
    Typically, what if my "product" names reside in a single key definition file ? How should I insert it ?

    ReplyDelete
    Replies
    1. Not sure that I understand. So if you have a DITA topic with multiple reusable elements (among which the product name) you can define a key for it and use conkeyref.

      Delete
  2. In addition, it would be good to know what happens to cross-references that point to the peeling.dita file.
    It turns out they point to the latest generated instance of this file, in this example, any xref to the peeling.dita file will point to the "cucumber" instance.

    ReplyDelete
    Replies
    1. In order for the publishing processor to have a clear idea how to resolve cross references to topics inside scopes, all cross references should be done using keyref.

      Delete
  3. Emily Dickinson wrote differently than this crowd. Nevertheless, thank you for your good explanation of branch filtering using element filter with the @audience attribute.

    ReplyDelete