Detail for bug fix item 7: Add mapref to map

[Don Day <dond@us.ibm.com>]

Mapref is considered a bug because the fallback mechanism using conref is considered flawed. This proposal does not impact any existing use of maps; it is fully backwards-compatible.

The mapref element provides a way to reuse another map within your map. This could be done, in concept, with the conref attribute on topicref and reltable. However, conref would not work for complicated maps. In order to reuse a map with ten top level elements, you would need to place an ID on all ten elements in the target map, and then conref each of those items. If the target map changed (adding or removing a top level element), you would not get the changes unless you also updated your conref values. In addition, if the target map contained a <navref> element at the top level, you would have to actually copy the element into your map, because navref does not use conref.

At its simplest, mapref provides a way to reference another map without having to worry about that map's contents. Because navref already implies a similar function, it can be redesigned as a specialization of mapref. Attributes on the mapref element will define how the mapref is processed. The toc attribute allows you to include the target map as part of your TOC, exclude it from the TOC, or link to it at run time (as with navref today). The linking attribute defines whether links should be generated based on the target map -- if this will be resolved at run time, you may not want to evaluate any link relationships at this point. Most other attributes are based on existing attributes on the map and topicref elements.

This also provides a mechanism to process several maps together. If you process each map individually, and maps reuse topics, you will not be able to get all of the links you need. The output from each map (with only that map's links) will overwrite the output from the previous map. The linking code in use within IBM is based on the idea that all related maps will be processed at one time. The mapref element provides a way to process a set of maps within the DITA architecture, without relying on another map list format.

Samples
This map shows how a collection of maps can be processed at one time:
<map title="map collection">
<mapref href=""first.ditamap"/> <mapref href=""second.ditamap"/> <mapref href=""online_info.ditamap"" print="no"/>
<mapref href=""reltables"" toc="exclude"/>
</map>

This map shows how target maps can be instanced inside existing navigation:
<map title="Book">
<topichead navtitle="Chapter 1">
<mapref href=""chapter_one.ditamap"/> </topichead>
<topichead navtitle="Chapter 2">
...
<mapref href=""common_setup_instructions.ditamap"/> <!-- The following map will be linked to at run-time; could also use navref -->
<mapref href=""../com.company.product/more_info.ditamap"" toc="link"/>
...
</topichead>

Regards,
--
Don Day <dond@us.ibm.com>
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
11501 Burnet Rd., MS 9037D018, Austin TX 78758
Ph. 512-838-8550 (T/L 678-8550)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot