Cross-referencing a ditamap

Cross-references to ditamaps should not be used, because DITA does not have a clear method for doing so, and the logic of linking to metadata is not strong.

Creating a cross-reference to a ditamap may at first seem to be unremarkable. On reflection, however, cross-referencing a ditamap is problematic.

A ditamap is a specification for a published document, or for part of a document (if nested or modular ditamaps are being used). As such, the ditamap itself contains no content, and it doesn't make sense to link to nothing! More logically, the cross-reference should be to the first topic referenced by the ditamap.

The solution is not as clear-cut as that, unfortunately. There are times when you might want to cross-reference a chapter, as in "described in Chapter 2". Chapter infrastructures are defined in the map, and although they are not content, they are still likely targets of a cross-reference. In any case, DITA topics are intended to be context-agnostic, so cross-referencing a ditamap would restrict that topic's use to publications where the referenced ditamap is also included.

Further, DITA has no clear mechanism for cross-referencing ditamap topicref elements.

Avoid cross-references to ditamaps. If required, it may be better to cross-reference to the published version of the ditamap, such as the PDF location or Web URL.