VideosDITA Root Map


This video demonstration shows you how to avoid validation problems in your DITA Maps using the Root Map support to establish a key space, which you can use with any DITA Map that is imported by the Master File.


00:00:09In this demonstration we'll discuss the importance of setting the correct root map to your DITA
00:00:14maps hierarchy.
00:00:15For instance, processing key references requires that oXygen determines the effective binding
00:00:21of a given key to a resource in the context of a given root map.
00:00:26Since a root map defines the set of effective key bindings, this process is known as
00:00:33establishing a key space.
00:00:34To correctly reflect the DITA rules for key definitions, oXygen builds the key space starting
00:00:40from a root map.
00:00:42As a practical example, we'll work with a DITA map structure composed of a root map
00:00:47that references two sub-maps.
00:00:51In our sample project, both the "Flowers" map and the "FlowersByFamily" sub-map define
00:00:57different keys.
00:00:59When the "Flowers" map is set as a root map, oXygen constructs the key space by collecting
00:01:04keys from the entire map structure.
00:01:07Since documentation projects can often produce huge DITA map structures (with a DITA map
00:01:13that refers many other sub-maps) you might want to focus on one specific sub-map at a time.
00:01:21To highlight the benefits of selecting the correct root map, we'll begin our demonstration
00:01:26by working with the "FlowersBySeason" sub-map as an independent map.
00:01:31As you can see, the DITA Maps Manager View marks the two referred sub-maps with special icons.
00:01:38When we open the first sub-map...
00:01:41...we notice an error.
00:01:43The problem is that the definition of a key is not found.
00:01:47Furthermore, if we open one of the topics, for example "Chrysanthemum", and try to validate
00:01:55it, oXygen reports that the definition of two of the keys used in the topic are not found.
00:02:02The first warning reports that a link that uses a key reference cannot be resolved because
00:02:08the key definition is not found.
00:02:10The second warning has the same cause, but this time we have a broken content key reference.
00:02:18Also, if we want to insert a keyref, we can see that oXygen does not find any key definition.
00:02:26See that the key definition table is empty.
00:02:30The problem is that the map is isolated from the rest of the map structure.
00:02:35Note that the Root Map selector is set to "Current Map" and therefore oXygen considers
00:02:41that the root map is "flowersBySeason".
00:02:43You can change the root map from the DITA Maps Manager view or by clicking one of the
00:02:50key , reference errors... or from one of the "Insert Link" dialog boxes.
00:03:12You can see that oXygen has now collected the key definitions.
00:03:16Note that the Root map selector was updated to "flowers.ditamap".
00:03:22From now on, we can use the key definitions in any of the maps within the map structure.
00:03:29If we validate the topic again, oXygen won't report any problems.
00:03:34Also, the content reference was solved and now it is displayed correctly.
00:03:42The root map also defines the scope of the Rename operation.
00:03:47For example, our map structure references the "Chrysanthemum" topic twice: once in the
00:03:53"flowersBySeasons" map and once in the "flowersByFamily" map.
00:03:57So, if we want to rename the "Chrysanthemum" file, we should be aware that all of its references
00:04:04need to be updated correctly.
00:04:06To see how it works, we'll switch the Root map back to , meaning that oXygen
00:04:12will consider "flowersBySeasons" to be the root map, thus detaching it from the maps structure.
00:04:20Now, oXygen narrows the scope of the Rename operation to the "flowersBySeason" submap only.
00:04:26If we try to rename the "Chrysanthemum" topic file ...
00:04:37we see that oXygen finds only one reference.
00:04:43But if we set the Root map to "flowers.ditamap", the scope of the Rename operation will be
00:04:50the entire map structure.
00:04:53If we try to rename the file again,
00:04:59oXygen detects the "Chrysanthemum" topic in both submaps.
00:05:08And this concludes our demonstration.
00:05:10Thank you for watching.