VideosDITA Root Map
Overview
Duration: 04:54
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.
Transcript
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.
Related Videos
|
Use Oxygen Feedback to ask us anything about this video.