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. On the other hand, this mechanism also increases the reusability of those ditamap files.

You can create references to another ditamap file by setting the format attribute as follows.
Note: This usage is so-called mapref. But in fact, there is no <mapref> element in use.
  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 URL format. Typically it is a relative path to the file.
  3. Set format="ditamap".
  4. Add a navigation title in the navtitle attribute.

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="sample\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="sample\mysample.ditamap" navtitle="sample ditamap"/>
  </topicref>
</map> 
        

If, for example, the content of the mysample.ditamap is shown 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-futures.xml" navtitle="DITA futures"/>
  <topicref href="..\DITA-installation.xml" navtitle="Installation"/>
</map> 
        

then the readme.ditamap file can be equivalently expressed by the following codes:


<?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-futures.xml" navtitle="DITA futures"/> 
    <topicref href="DITA-installation.xml" navtitle="Installation"/>
  </topicref> 
</map>