Chapter 4. Map-Driven Processing

Using and extending the DITA for Publishers map-driven processing framework

DITA for Publishers provides general map-driven processing whereby the output generation for each topic is driven by processing of the root input map. This allows each topic to be processed with full knowledge of its use context in the map. This in turn enables a number of important functions:
  • Numbering of topics and within-topic elements in terms of the topicref hierarchy in the map ("enumeration").
  • Processing of topics in terms of semantics imposed by topicrefs (e.g., processing a generic topic as a "chapter" because it is referenced by a <chapter> topicref).
  • Distinguishing separate uses of the same topic within a map in order to do automatic chunking and link rewriting.
  • Generating output files in a structure different from the source file organization structure.
  • Generation of literal files for topic heads as though the topic heads were references to title-only topics.
  • Generation of a back-of-the-book indexes, glossaries, and other publication-scope lists.

The map-driven processing is used by all the DITA for Publishers transformation types, including HTML2, HTML5, EPUB, and Kindle. It is intended to be a general facility that can be used with any output type.

The general processing model uses two main phases:
  1. Data collection
  2. Output generation
The data collection phase operates on the map and its topics to build up a single XML structure that contains the information needed to do the following:
  • Number things using normal XSLT numbering facilities (e.g., <xsl:number>) (enumeration support).
  • Index entries grouped and sorted for use in generating back-of-the-book indexes
  • Glossary entries grouped and sorted for use in generating glossary lists
The output generation phase produces whatever the final result is, e.g., HTML. All output generation phase processing is provided the collected data as a tunnel parameter named "collected-data". You can access this variable by adding the following <xsl:param> to any template:
<xsl:template ...>
  <xsl:param name="collected-data" as="element()" tunnel="yes"/>

You can extend the data collection processing using any of several defined extension points.