Re: [dita] Errata: Example Domain Constraint Will Not Work

["Robert D Anderson" <robander@us.ibm.com>]

Right - the example in the specification is correct and it works, but both the delivered 1.3 learning shells and the delivered learning constraint were wrong.

I sent my revised constraint to Eliot yesterday. It's not implemented like the sample in the spec, but it works, and I thought it was correct when I did it. Which brings me to the comment in Eliot's first note:
> However, since the coding rules are just guidelines it doesn't
> really matter—DTD syntax determines where things have to go.

I must admit this really makes my head spin. Section 2.6 of the base spec (Coding practices for DITA grammar files) runs from page 149 to 177. Those practices are rules (not guidelines) - stating factual information about how the modules have to be coded. Following these rules will get you "DITA-conforming grammar files", as defined by DITA 1.3.

If they're just guidelines, why do we devote 28 pages of the specification to defining them as normative rules?

If they're really just guidelines (and I think they're better off as guidelines!), maybe we can consider moving them out of the 2.0 spec, and into a tutorial or companion spec devoted just to interchangeable / modular grammar files?

And after lighting that fuse, I'll send my regrets in for the next two meetings ;-)

Regards, 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

Eliot Kimber ---07/14/2016 11:39:48 AM---Strike this comment: I just realized we do in fact account for this in the spec, I had just forgotte

From: Eliot Kimber <ekimber@contrext.com>
To: Eliot Kimber <ekimber@contrext.com>, DITA TC <dita@lists.oasis-open.org>
Date: 07/14/2016 11:39 AM
Subject: Re: [dita] Errata: Example Domain Constraint Will Not Work
Sent by: <dita@lists.oasis-open.org>

---

Strike this comment: I just realized we do in fact account for this in the spec, I had just forgotten.

So the example is correct, just the L&T constraint and shells are wrong.

Cheers,

E.
----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com

From: dita <dita@lists.oasis-open.org> on behalf of Eliot Kimber <ekimber@contrext.com>
Date: Thursday, July 14, 2016 at 11:34 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Errata: Example Domain Constraint Will Not Work

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

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php