Bitesize DITA – Branch filtering

In the last two Bitesize DITA articles we’ve been looking at the most common ways to manage variable content, through keys and through conditional filtering. Changes to the DITA 1.3 spec offer us some more sophisticated filtering options that may be useful.

Branch filtering enables us to apply more than one DITAVAL file to a map – so that you can filter different parts of the map according to different criteria. This is useful for omnibus publications, where you may want to document a family of similar products in the same manual, or where you want to include information that is specific to different platforms (perhaps different instructions for Mac, Windows and Linux users) within the same publication.

The mechanism for branch filtering is to reference the ditaval file using the <ditavalref> element, new to the 1.3 standard.  The element itself looks and behaves very much like any other DITA reference, with the href attribute pointing to the location of the DITAVAL file. So instead of pointing to a DITAVAL file at processing time, it actually gets incorporated into our DITA map:

In this example, we have two identical topics that contain content flagged with the platform attribute:

We’re going to use this topic twice in the same map, but apply different filters – one to exclude the Mac content and one to exclude the Windows content.

 

You can incorporate the DITAVAL file into your map as part of a submap, or, as I have here, applying it to branches of a single map underneath a <topichead> element, or in any other hierarchical arrangement of topics.  There needs to be some idea of topic ‘branches’ though – partly because it doesn’t really make any sense to filter the same batch of topics on two potentially conflicting filtering criteria, but also because the publication will fail.

So, in the output, we have a Windows and a Mac version in the same document, using the same topics.

 

To output correctly, your authoring environment will need to have a version of the DITA Open Toolkit that supports the 1.3 standard.  

Branch filtering offers us another tool in the toolbox, and as with all the others, it is up to us as authors and Information Architects to evaluate whether or not it does a useful job for our content. The same considerations apply as for any other filtering operation though – be mindful of whether your conditions might grow (and grow into a mess) and think about the strengths of conditional filtering – that it usually works best with a small, closed set of conditions with very clear boundaries in terms of what is and isn’t included.

If you’re wondering about the 1.3 spec and what it means for you – Mekon can help. We offer training and consultancy to suit your needs and budget – whether it’s a quick tune-up or a more extensive coaching programme. Contact us on +44 (0)208 722 8400 or email

View more Bitesize DITA tips, tricks and insights

If you have a question or a useful tip to share, why not tweet us @BiteSizeDITA

DITA Training

Looking to develop your DITA skills? Book your place on one of our DITA training courses. Mekon offer a range of DITA training to suit your specific needs:

Our specialist training courses can be delivered as a standalone training course, or as part of an integrated, customised solution. We deliver our courses in a number of ways, here at Mekon, on site with you or remote.

Find out more