Mapref

Mapref refers to a special usage of the <topicref> element as a reference to another ditamap file. This allows you to manage the overall ditamap file more easily. A large ditamap file can thus be broken down into several ditamap files, making it easier for the user to manage the overall logical structure. This mechanism also increases the reusability of those ditamap files.

You can create references to another ditamap file by setting the format attribute to "ditamap" as follows.
Note: This usage is often referred to as mapref. A new mapref element is defined in DITA 1.2, which provides a shortcut for this function by defaulting the format attribute to "ditamap". However, any topicref or topicref specialization may do the same thing by setting the format attribute as described.
  1. Add a <topicref> element to your map.
  2. Define the location of the target ditamap file in the href attribute. The href takes a standard URI format. Typically it is a relative path to the ditamap.
  3. Set format="ditamap".
  4. Optional: Add a navigation title in the navtitle attribute. The navtitle attribute on a map reference is not used for anything during DITA-OT processing, but is helpful when authoring.

For example, if you want to create a reference to the samples/mysamp.ditamap file using sample ditamap as the navigation title, add the following codes into the readme.ditamap file.

<topicref format="ditamap" href="samples/mysample.ditamap" navtitle="sample ditamap">
Now the complete content of the readme.ditamap file is shown as follows. 
<?xml version="1.0" encoding="utf-8"?>           
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="mainDITAreadme" title="DITA Readme map">
  <topicref collection-type="family" href="DITA-readme.xml" id="DITA-doc" 
           locktitle="yes" navtitle="DITA-OT Introduction"> 
    <topicref href="DITA-changes.xml" navtitle="DITA release history"/>
    <topicref format="ditamap" href="samples/mysample.ditamap" navtitle="sample ditamap"/>
  </topicref>
</map>
Assume the file samples/mysample.ditamap is defined as follows:
<?xml version="1.0" encoding="utf-8"?> 
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> 
<map id="samplemap" title="Sample Ditamap"> 
  <topicref href="..\DITA-relnotes.xml" navtitle="DITA OT Release notes"/>
  <topicref href="..\DITA-installation.xml" navtitle="Installation"/>
</map>

The readme.ditamap file can be equivalently expressed by the following map:

<?xml version="1.0" encoding="utf-8"?> 
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> 
<map id="mainDITAreadme" title="DITA Readme map"> 
  <topicref collection-type="family" href="DITA-readme.xml" 
           id="DITA-doc" locktitle="yes" navtitle="DITA-OT Introduction">
    <topicref href="DITA-changes.xml" navtitle="DITA release history"/> 
    <topicref href="DITA-relnotes.xml" navtitle="DITA OT Release notes"/> 
    <topicref href="DITA-installation.xml" navtitle="Installation"/>
  </topicref> 
</map>