Nested mapref elements generate error message

[stevebang]

Since the <mapref ...> element is "a convenience element" equivalent to the <topicref format="ditamap" ...> element, I was surprised to see an error message when I converted nested <topicref format="ditamap" ...> elements to <mapref> elements, like this:

Code: Select all

     <mapref...>

          <topicref format="ditamap" .../>

     </mapref>

Here is the error generated during validation in Oxygen XML Editor 18.1 (using the DITA 1.3 validation):

E [Xerces] Unexpected element "mapref". The content of the parent type must match "(topicmeta?,(data|sort-as|data-about)*)*.

No errors not appear when using nested <topicref format="ditamap" ...> elements, like this

Code: Select all

     <topicref format="ditamap" ...>

          <topicref format="ditamap" .../>

     </topicref>

Errors are also not generated when nesting a <mapref> within a <topicref format="ditamap" ...> or nesting a <topicref format="ditamap" ...> within a <mapref> element.

So, it would seem to be a bug not to allow the "convenience" element equivalent (<mapref>) when nested. That's rather inconvenient.

Steve

[Radu]

Hi Steve,

According to the DITA specs the mapref element cannot contain nested topicref elements:

https://www.oxygenxml.com/dita/1.3/spec ... tm__mapref

Generally speaking from what I remember discussing with the DITA specs committee references to DITA Maps should not have any other topicrefs nested inside them. The specification states something like this:

https://www.oxygenxml.com/dita/1.3/spec ... ibute.html

If a <topicref> element that references a map contains child <topicref> elements, the processing behavior regarding the child <topicref> elements is undefined.

The reason why the validation does not complain about this:

Code: Select all

<topicref href="a.ditamap" format="ditamap">

<topicref href="b.ditamap" format="ditamap"/>

</topicref>

is that the DTD schemas used to validate the DITA map are not complex enough to describe this constraint.

Regards,
Radu

[stevebang]

Thanks, Radu -- I inherited a tangled mess of DITA maps and book maps, with many errors and incomplete efforts, so when the previous code didn't generate an error on this until I switched to the easier to read <mapref> elements, I thought it was an error in handling the <mapref> elements. On an example page (https://www.oxygenxml.com/dita/1.3/spec ... ?hl=mapref), I guess that I misinterpreted how it could make sense that either <mapref> or <topicref format="ditamap"> elements could reasonably nest and work.

I also guess that the warnings I see about inherited type="content" for <topicref format="ditamap"> or <mapref> elements are nonsensical since it doesn't make sense that a DITA map inherits a "content" type.

Steve

[Radu]

Hi Steve,

About the @type attribute:

https://www.oxygenxml.com/dita/1.3/spec ... ibute.html

If not explicitly specified on an element, the @type attribute value cascades from the closest ancestor element.

If the @type attribute is specified when referencing DITA content, it should match one of the values in the referenced element's @class attribute. The @type value can be an unqualified local name (for example, "fig") or a qualified name exactly as specified in the @class attribute (for example, "mymodule/mytype").
Applications MAY issue a warning when the specified or inherited @type attribute value does not match the target (or a specialization ancestor of the target).

So when the @type attribute is specified on a topicref the specs says that it should match the @class attribute value of the referenced topic. Basically you can use type="task" to refer to a task, type="topic" to refer to a topic or to a task and so on.
Most of the times the @type attribute does not need to be present at all explicitly on the topicref because the processor should infer it from the type of target that is referenced.
But as I've encountered before there are DITA projects that use the @type attribute to set various custom type values on the topicref.
I'm not sure how these custom values (you mentioned 'type="content"') are later used, maybe there are client specific publishing customizations which may use these values for something...
Also the type attribute cascades on the topicrefs which do not specify it. So once you start using @type you kind of need to use it on all topicrefs, otherwise its value will cascade from an ancestor topicref.

Regards,
Radu

[stevebang]

Hi Radu--

I think I understand how the type attribute works and had carefully reviewed that link a while ago. What I'm referring to is that when validating a DITA map, I'm seeing the following warning message:

W [REF] Reference is made with inherited @type "task" to a DITA resource with class "-map/map".

I understand that the type cascades (or is inherited) to the nested <topicref> or <mapref>, but since the "concept" type doesn't really apply to a map, it seems nonsensical to display that as a warning unless that is just letting the user know that the <topicref> children of that map will also inherit the "task" type value.

Steve

[Radu]

Hi Steve,

You are probably right, maybe we should not issue this warning in this case. I will add an internal issue for this.

Regards,
Radu

[stevebang]

Thanks, Radu, for following my thinking on this topic. Here's a further case to consider....

I get the following warning:

W [REF] Reference is made with inherited @type "concept" to a DITA resource with class "-topic/topic reference/reference".

which applies to the most nested <topicref> here:

Code: Select all

<topicref format="dita" href="c_SQL_reference.xml" navtitle="SQL reference" scope="local" type="concept">

     <topicref format="dita" href="r_conditions.xml" navtitle="Conditions" scope="local" type="reference">

          <topicref format="dita" href="r_patternmatching_condition_like.xml" navtitle="Pattern-matching condition" scope="local" type="reference"/>

     </topicref>

</topicref>

Based on the expected type attribute cascading, it seems odd to get the warning because the top "concept" type (in line 1) doesn't apply to the most nested "reference" type (in line 3) since (a) type is explicitly specified as "reference" and (b) the parent (in line 2) specifies "reference", which would be inherited by the child <topicref> in line 3. [Note: code simplified; removed other <topicref> elements not related to this issue.]

It would be great to not get warnings for these, if possible.

Steve

[Radu]

Hi Steve,

I'm sorry but I cannot reproduce this problem. So in a DITA Map I added the topicref structure you posted and created 3 new files on disk: c_SQL_reference.xml as a concept, r_conditions.xml and r_patternmatching_condition_like.xml as references.
I get no problem when using the "Validate and check for Completeness". I tested with Oxygen 18.1.
Could you try to come up with a cut-down sample DITA project to reproduce the issue and send it to us (support@oxygenxml.com)?

Regards,
Radu

[stevebang]

Thanks, Radu, for trying to reproduce this. I should be able to retest the scenario and send you files required to reproduce this. I will do this in the morning at work, in Palo Alto.

Steve