New DITA 2.0 Stage 1 Proposal: User-defined topicref format mappers

[Chris Nitchie <chris.nitchie@oberontech.com>]

I firmly believe that if DITA can't find a way to marry documentation authored in other formats with its native structured content, it's going to struggle to stay relevant. Lightweight DITA, with support for format="mdita" and format="hdita", is a giant leap forward on this front. DITA 2.0 should mandate support for those formats, and go further by allowing map authors and DITA implementers to declare support for other formats as well.

I’m envisioning something like a new element inside <topicmeta> that would describe the mappings to apply for specific @format values at and beneath the enclosing element in the resolved map tree. Something like this:

<map>
  <topicmeta>
    <format-mappings>
      <format-mapping format="csv"
          processor="http://www.example.com/dita/formats/csv-as-simpletable";>
        <mapping-param name="tableId" value="table"/>
        <mapping-param name="titleStrategy" value="navtitle,filename"/>
      </format-mapping>
      <format-mapping format="tld"
          processor="http://www.example.com/dita/formats/xsl";>
        <mapping-param name="stylesheet" href="tld-to-topic.xsl"/>
      </format-mapping>
    </format-mappings>
  </topicmeta>
  
  <!-- Processed with vnd-csv-as-simpletable -->
  <topicref href="file.csv" format="csv"/>
  
  <!-- Processed with the XSL transform tld-to-topic.xsl -->
  <topicref href="jsp-tag-library.tld" format="tld"/>
  
  <!-- Processed with a custom CSV mapping -->
  <topicref href="file2.csv" format="csv">
    <topicmeta>
      <format-mappings>
        <format-mapping format="csv"
          processor="http://www.example.com/dita/formats/csv-as-oasis-table"/>
      </format-mappings>
    </topicmeta>
  </topicref>
</map>

Processors are declared using URIs to ensure uniqueness, and potentially to provide a location for documentation. Processors may also define protocols by which the URI can be used to discover a mapping processor's implementation at runtime, but such protocols are outside the scope of the standard.

The execution of content mapping would happen very early in DITA preprocessing, after the key space structure is built (so you can use @keyref on <mapping-param>) but before any topic content is loaded, such that any content referenced through a defined mapping would be treated as a normal DITA topic for the majority of the operation.

This provides the following benefits:

- Provides a loosely-defined mechanism by which DITA users can declare support for inclusion of arbitrary non-DITA documentation sources into DITA publications.
- Allows references to all or parts of such documents using normal DITA referencing techniques (links, xrefs, conrefs).
- Allows map authors to define different content mapping strategies at different locations in the map hierarchy.
- Makes formerly-implicit dependencies on special format handlers explicit, so that processors lacking the necessary support for a given format can take appropriate actions.

That last point could use some unpacking. Newer versions of the DITA-OT come with support for the lightweight DITA hdita and mdita formats. DITA 1.3 makes no mention of hdita and mdita, but users of the OT are able to use them freely. Unfortunately, their content will almost certainly not be processed as expected in a non-OT system, or in another older OT installation lacking the LwDITA plugin. The content is already tied to a specific processor configuration, but that dependency is hidden. Another perfectly DITA 1.3-compliant processor, encountering a topicref with format="mdita", will do something else with that topicref, but almost certainly not what the user expects. With this proposal, such dependencies are made explicit, so that processors without the required support can, at least, issue warnings to that effect, or, if they're fancy, attempt to identify and install support for the format on the fly using some application-defined protocol based on the mapping processor URI.

Chris