Re: <mapref> does not allow <ditavalref> (and can this be supported in DITA 2.0?)

[Robert Anderson <robert.dan.anderson@oracle.com>]

Hi Chris,

This isn't exactly an oversight, it's more a quirk of the grammar and how domains work.

As you may know, the way that domains usually work is that they appear anywhere that the base element appears. So without additional configuration, the <ditavalref> element will appear everywhere that <topicref> appears, and nowhere else. Because the <mapref> convenience element does not allow that base <topicref> element, it also does not allow <ditavalref>.

One way to get <ditavalref> inside of map references is to add topicref as a valid child - but this is intentionally excluded, because it would bring in a large set of elements that explicitly has no meaning inside of a map reference. We really want to avoid doing that.

Alternatively, it would be possible to allow only <ditavalref> inside of the map reference, but it would have unfortunate consequences.

Because both <mapref> and <ditavalref> are specialized from <topicref>, and that base topic reference element can nest itself, it would be valid for OASIS to explicitly allow <ditavalref> in <mapref>. This would be accomplished simply by adding <ditavalref> to the content model, without adding <topicref>. However, this would set up a dependency on the domain -- once that is explicitly defined as a child, any map grammar that uses the <mapref> element must also use the DITAVAL reference domain.

Right now, my expectation is that nearly all (or possibly all) map configurations out in the wild use the map group domain - those convenience elements are extremely useful. At the same time, I know that a lot of people remove the ditavalref domain, because it's an advanced feature that is not needed everywhere. If <mapref> is updated to explicitly allow <ditavalref>, this becomes impossible - every map that uses any of the map group elements would also need to include the ditavalref domain.

After talking this through at the technical committee, we're not expecting to change this for 2.0 - the downsides of either approach do not seem worth the benefit for this convenience element, when you can get the behavior by using a general topicref element.

Thanks,

Robert

---

From: Chris Papademetrious <Christopher.Papademetrious@synopsys.com>
Sent: Monday, March 21, 2022 6:18 PM
To: dita-comment@lists.oasis-open.org <dita-comment@lists.oasis-open.org>
Subject: [External] : [dita-comment] <mapref> does not allow <ditavalref> (and can this be supported in DITA 2.0?)

 

Hello DITA TC folks!

 

To apply <ditavalref> to a map, a <topicref> map reference is valid:

 

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

  <ditavalref href="">

</topicref>

 

but a <mapref> map reference is not valid:

 

<mapref href="">

  <ditavalref href="">

</topicref>

 

The first example is taken from Figure 1 at

 

https://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/example-ditavalref-with-mapref.html

 

I confirmed this in the DITA 1.3 content models:

 

topicref = element topicref { topicmeta?, (anchor | data | sort-as | data-about | navref | topicref | anchorref | keydef | mapref | topicgroup | topichead | topicset | topicsetref | ditavalref)* }

mapref = element mapref { topicmeta?, (data | sort-as | data-about)* }

 

and in the DITA 2.0 content models:

 

topicref = element topicref { topicmeta?, (data* | navref | topicref | ditavalref | keydef | mapref | mapresources | topicgroup | topichead)+ }

mapref = element mapref { topicmeta?, (data*)+ }

 

I understand that a map reference is a convenience element that by nature cannot contain content, but I suspect that the omission of <ditavalref> from its content model might have been unintentionally omitted when it was reduced.

 

If unintentional, can this be supported in DITA 2.0? <mapref> provides valuable visual differentiation when scanning down the left side of a map, avoiding the need to wade further into the sea of attributes to look at @href file extensions and @format values.

 

Thanks!

 

- Chris

 

-----
Chris Papademetrious

Tech Writer, Implementation Group

(610) 628-9718 home office

(570) 460-6078 cell