Changes to the specification can take time to bed down – as well as the time needed to develop support in CCMSs and authoring tools, there’s an organic process of establishing real use cases and a body of good practice. It’s a bit like musical repertoire – some parts of the spec are equivalent to ‘Happy Birthday’ – that the whole community knows and uses, but there is also opera and avant-garde jazz and folk music. Scoped keys are still a bit of a new song at the moment. But the principle behind them is that, instead of a map referring to a single key applicable throughout the whole map, we can define which parts of a map a particular key applies to – whether it’s a map, a submap, a topichead element or an individual topicref.
At the moment the main use case for scoped keys seems to mostly be for ‘omnibus publications’ – for example a manual which uses the same topics, describing the same functions and features, but for multiple products.
In this example we’re going to create an omnibus manual for three different products in the same family of tractors – the MekonFarm Homestead H5 series. Each product has its own map, containing two topics that are identical for all maps:
The topics are called About your tractor and Safe operation. Each map is referenced in a root map:
In the root map I’ve defined the Key ProdName with three different values, to represent three different products. I’ve given each key a keyscope that we can then use to define where each different value should be used.
Then for each of the maprefs in the root map, I’ve set the keyscope attribute to match the appropriate keyscope for the product name.
Our generic topics will pick up not just the value specified in the key definition, but the value specified in the key definition with the correct keyscope attribute:
So the same topic, referencing the same key can pick up different values depending on which keyscope attribute is applied to the mapref, topicref or topicgroup referencing the topic.
This means that when the map is published, each instance of the generic topics picks up a different ProdName keyword because it’s in a different map with a different keyscope:
In situations where you have generic repeated content that is the same apart from slight differences such a product names, part names / numbers or other variables, using the keyscope attribute enables you to keep that generic content generic, and therefore reusable.
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.