Cascading of metadata elements from submap

[lief-erickson]

What is the expected behavior for element metadata cascading from submaps?

root-map.ditamap

<map id="root-map">
  <topicmeta>
    <category>one</category>
  </topicmeta>
  <mapref href="submap.ditamap"/>
</map>

submap.ditamap

<map id="submap">
  <topicmeta>
    <category>two</category>
  </topicmeta>
  <topicref href="topic.dita"/>
</map>

topic.dita

<concept>
  <prolog>
    <metadata>
      <category>three</category>
    </metadata>
  </prolog>
  ...
</concept>

According to the specification, <category> should be additive. And it kinda is. Using the html5 and normalized dita transtypes, the output for topic.dita in temp.dir is:

<concept>
  <prolog>
    <metadata>
      <category>one</category>
      <category>three</category>
    </metadata>
  </prolog>
  ...
</concept>

The <audience>two</audience> element is discarded and nowhere to be found. Is this expected behavior?

This alternative construct using the root map produces the same results.

root-map-alternative.ditamap

<map id="root-map-alt">
  <topicmeta>
    <category>one</category>
  </topicmeta>
  <mapref href="submap.ditamap">
    <topicmeta>
      <category>two</category>
    </topicmeta>
  </mapref>
</map>

DITA-OT version 3.7.0

[chrispy-snps]

References to .ditamap files are resolved during the mapref stage of preprocessing, which is implemented in the following stylesheet:

${DITAOT}/plugins/org.dita.base/xsl/preprocess/maprefImpl.xsl

This code replaces an element referencing a .ditamap files with the inlined content of that submap file. However, during this replacement, any metadata inside the .ditamap-referencing element itself is discarded.

Here is a testcase: 3927.zip

Here is the result of the mapref preprocessing stage:

[chrispy-snps]

@lief-erickson - I noticed that in 2.2.4.6.2 Cascading of metadata elements from map to map, there is an example showing how metadata inside a map-reference element should propagate to the topics. So this might be a case where the DITA-OT does not fully implement the OASIS DITA specification.

You could file an issue if this is functionality you need in your publishing pipeline.

[kirkilj]

We're seeing this too and is a blocker for us migrating to our new help browser based on HTML5.

[kirkilj]

@robander, when you add your comments here, can you provide some info on exactly where we would to apply a patch until a fix is in OT, including the submap container element you mentioned?

[kirkilj]

I tested against 4.0.1 and it also drops those nested map-level topicmeta elements.

[robander]

@kirkilj As @chrispy-snps noted in screen caps yesterday, there are invented elements created during processing to hold metadata from submaps. I introduced that a few years back in DITA-OT 3.0. At the time my requirement was to save the titles, the metadata came along for the ride just because it seemed like I should grab that too, but - partly because it was not my main driver at the time - I did not try to reconcile the various issues that would arise with cascading of that metadata. Instead I tried to set it up in a way that the metadata is newly available for people who want to customize and make use of it, but for everyone else I don't change the existing behavior.

A summary of how it works is:

• When resolving submaps in the mapref stage, it creates the topicmeta container element: https://github.com/dita-ot/dita-ot/blame/bb8c8343a9d5890f6adf215e14737e97f9a4ff50/src/main/plugins/org.dita.base/xsl/preprocess/maprefImpl.xsl#L461
• It's done as a foreign specialization so that 1) it remains valid DITA but 2) it doesn't break anything people are used to (it's ignored unless you customize)
• This means if you want to make use of the content, it can be done after mapref, which is likely clear (it's not in the resolved map until we make the resolved map)
• The cleanup step at the end of preprocess removes this element, along with the other generated content we create to optimize moving between steps:

  dita-ot/src/main/plugins/org.dita.base/xsl/preprocess/clean-map.xsl

  Lines 27 to 29 in 9d0ad74

  	<xsl:template match="*[contains(@class, ' ditaot-d/submap-title ')]"/>
  	<xsl:template match="*[contains(@class, ' ditaot-d/submap-topicmeta ')]"/>
  	<xsl:template match="*[contains(@class, ' ditaot-d/submap-topicmeta-container ')]"/>

• This means if you want to make use of this in a plugin, you'd need to insert your code after mapref and before clean-map. If you'd like to get this content to cascade, the likely step would be to move it into the actual hierarchy after mapref + before "mappull" implements the cascading.