Errata: Example Domain Constraint Will Not Work

[Eliot Kimber <ekimber@contrext.com>]

In working through the correction for the learning object and learning group map constraints and reviewing the 1.3 spec language around constraints I noticed that the example topic for doing a domain constraint is wrong:

http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/example-contraints-subset-domain.html

It is wrong in the same way that the DTD version of learning object and learning group map DTDs are wrong, namely that the constraint module must precede the inclusion of the .ent file for the domain being overridden.

This is because the .ent files for domains define the content model extension parameter entities (e.g., %mapgroup-d-topicref).

Thus if the constraint module that wants to override this parameter entity is included after the .ent file, it will have no effect (which is one of the problems Robert found).

This is really a weakness in the way the constraint coding rules are defined—we never provided explicit accommodation for this particular case. However, since the coding rules are just guidelines it doesn't really matter—DTD syntax determines where things have to go.

I think this probably requires another errata item. I can propose a rewrite of the example topic.

Cheers,

Eliot

----

Eliot Kimber, Owner

Contrext, LLC

http://contrext.com

From: dita <dita@lists.oasis-open.org> on behalf of Robert Anderson <robander@us.ibm.com>
Date: Wednesday, June 29, 2016 at 12:56 PM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Found problem with learningObjectMap, learningGroMap DTDs

Hi,

Yesterday I discovered an unfortunate issue with the learningObjectMap and learningGroupMap DTDs while working on the contains / contained-by tables.

Each of these maps includes a constraint module, learningAggregationsTopicrefConstraint. Unfortunately this constraint is working in the RNG grammar files, not working in the DTD, and unclear in the XSD.

The purpose of the constraint is to say - "in any location that would normally allow <topicref> and its domain extensions, only allow keydef, mapref, and topicgroup". This means that the constraint removes the following elements:
* topicref
* From mapgroup domain: anchorref, topichead, topicset, topicsetref

I believe this works in the RNG. As a child of <learningObjectMap>, the legal topic references include the 3 expected, plus learningObject, learningGroup, learningObjectMapRef, and learningGroupMapRef. It also allows <ditavalref>, which is added as an independent domain. None of the excluded elements above are allowed.

The DTD constraint is not working - it allows everything that the RNG excludes:
* It is included in the wrong spot in the shell - so redefined entities are completely ignored
* The syntax in the constraint isn't quite right; moving it to the right spot in the shell results in a DTD that doesn't parse. It needs several changes in order to match what is done in RNG (drop topicref, add only 3 mapgroup extensions, and keep ditavalref).

I'd appreciate it if somebody could test the XSD - my test failed, not sure if it's a problem with my test or with the XSD itself.

Options moving forward:

• Fix the DTD (and maybe the XSD) in the errata. This has the potential to break any documents created with 1.3 using the learning maps. Kris points out to me that the RNG is normative, and that it might be better to break the few docs that exist today versus allowing 5 years of broken docs.
• Relax the RNG. But this does feel like more of a normative change.
• Almost status quo: DTD allows stuff that RNG doesn't (but fix the constraint module so that it *could* be used properly). This also raises the question "what should the containment models say in the appendix".

Thanks, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA