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.
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">
<?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>