OASIS Darwin Information Typing Architecture (DITA) TC

In going through the coding requirements for DTDs, Kris found a requirement from 1.2 (and earlier) that we think should be removed. However, it involves normative language, so we want to run it by the TC first. When coding structural specializations, the spec states that modules must define the included-domains parameter entity. This is usually empty but in some cases must have a meaningful default. See the (very short) rules and examples here: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdStructuralCodingReq.html Why is this meaningless? Every specialization, whether topic or map, structural or domain, builds on either the core topic module or the core map module. Both of those modules define the included-domains entity: <!ENTITY included-domains "" > When building a DTD, specialized modules must come after more general modules -- so every module comes after either topic or map. Within a DTD, the first definition wins. Thus, the required definition in a specialized module can never have any effect - the first definition from topic.mod or map.mod always wins. I think the straightforward change is to just remove this language, but as with other normative rules, the TC should sign off or quietly nod in approval before it goes away. Related: these entities were present in all of the 1.2 modules except the SubjectScheme map specialization. Each of the declarations was empty, and had no effect. They are not in the 1.3 modules we have in SVN now. Last year when I was comparing the output of Eliot's RNG->DTD tool with the actual shipped 1.2, I noted that extra definitions of the entity were missing, and I couldn't figure out why. This is why - the tool (reasonably) does not add the meaningless extra definition. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

Sounds reasonable to me. I am in favor of removing this language. Thanks and best regards, Scott Hudson Senior Consultant Comtech Services Inc. 303-232-7586 From: Robert D Anderson < robander@us.ibm.com > Date: Monday, February 23, 2015 at 3:16 PM To: DITA TC < dita@lists.oasis-open.org > Subject: [dita] Default values for @domains within specializations In going through the coding requirements for DTDs, Kris found a requirement from 1.2 (and earlier) that we think should be removed. However, it involves normative language, so we want to run it by the TC first. When coding structural specializations, the spec states that modules must define the included-domains parameter entity. This is usually empty but in some cases must have a meaningful default. See the (very short) rules and examples here: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdStructuralCodingReq.html Why is this meaningless? Every specialization, whether topic or map, structural or domain, builds on either the core topic module or the core map module. Both of those modules define the included-domains entity: <!ENTITY included-domains "" > When building a DTD, specialized modules must come after more general modules -- so every module comes after either topic or map. Within a DTD, the first definition wins. Thus, the required definition in a specialized module can never have any effect - the first definition from topic.mod or map.mod always wins. I think the straightforward change is to just remove this language, but as with other normative rules, the TC should sign off or quietly nod in approval before it goes away. Related: these entities were present in all of the 1.2 modules except the SubjectScheme map specialization. Each of the declarations was empty, and had no effect. They are not in the 1.3 modules we have in SVN now. Last year when I was comparing the output of Eliot's RNG->DTD tool with the actual shipped 1.2, I noted that extra definitions of the entity were missing, and I couldn't figure out why. This is why - the tool (reasonably) does not add the meaningless extra definition. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

I agree--not a useful rule. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 2/23/15, 4:16 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >In going through the coding requirements for DTDs, Kris found a >requirement from 1.2 (and earlier) that we think should be removed. >However, it involves normative language, so we want to run it by the TC >first. > >When coding structural specializations, the spec states that modules must >define the included-domains parameter entity. This is usually empty but >in some cases must have a meaningful default. See the (very short) rules >and examples here: > http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdStructuralCodingR >eq.html > >Why is this meaningless? Every specialization, whether topic or map, >structural or domain, builds on either the core topic module or the core >map module. Both of those modules define the included-domains entity: ><!ENTITY included-domains > "" >> > >When building a DTD, specialized modules must come after more general >modules -- so every module comes after either topic or map. Within a DTD, >the first definition wins. Thus, the required definition in a specialized >module can never have any effect - the first definition from topic.mod or >map.mod always wins. > >I think the straightforward change is to just remove this language, but >as with other normative rules, the TC should sign off or quietly nod in >approval before it goes away. > >Related: these entities were present in all of the 1.2 modules except the >SubjectScheme map specialization. Each of the declarations was empty, and >had no effect. They are not in the 1.3 modules we have in SVN now. Last >year when I was comparing the output of Eliot's RNG->DTD tool with the >actual shipped 1.2, I noted that extra definitions of the entity were >missing, and I couldn't figure out why. This is why - the tool >(reasonably) does not add the meaningless extra definition. > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )