dita — archive

[Kristen Eberlein]

Title: DTD: Coding requirements for constraint modules Text of updated DITA 1.3 spec topic for TC consideration. Many of the normative statements are significantly relaxed, and I suggest that we move coverage of file naming conventions to a non-normative appendix. Changed from the targeted review are highlighted in red. I wanted to get TC agreement about these changes before making similar changes to the RNG and XSD topics. Kris DTD: Coding requirements for constraint modules A structural constraint module defines the constraints for a map or topic element type. A domain constraint module defines the constraints for an element or attribute domain. Structural constraint modules Structural constraint modules have the following requirements: File names Structural constraint modules should be named using the following format: qualifier Tagname Constraint.mod where: qualifier is a string that is specific to the constraints module and characterizes it, for example, strict or requiredTitle or myCompany- . Tagname is the element type name with an initial capital, for example, Taskbody or Topic . For example, the file name for the constraint that is applied to the general task to create the strict task is strictTaskbodyConstraint.mod . Draft comment: Kristen Eberlein 24 January 2015 I changed the SHOULD to should . File naming conventions are best practices; they are not normative. The qualifier variable is completely arbitrary and cannot be enforced. I suggest that we move this content to a non-normative appendix. Entity name and value The constraint module SHOULD contain a declaration for a text entity with the following name: tagname -constraints where tagname is the name of the element type to which the constraints apply. The value of the text entity MUST use the following format: ( inheritance-hierachy qualifier Tagname -c) where: inheritance-hierachy is the specialization hierarchy, for example, topic task . qualifier is a string that is specific to the constraints module and characterizes it, for example, strict or requiredTitle or myCompany- . Tagname is the element type name with an initial capital, for example, Taskbody or Topic . The literal -c indicates that the name is the name of a constraint. The value of the text entity contains the contribution to the @domains attribute for the constraint module. For example, the following text entity provides the declaration for the strict task constraint that is shipped with the DITA standard. <!ENTITY taskbody-constraints (topic task strictTaskbody-c) > Optionally, a domains contribution can indicate a strong constraint by preceding the domains contribution with the letter s . For example, s(topic task strictTaskbody-c) indicates a strong constraint. The %tagname.attributes; parameter entity When the attributes for an elements are restricted, there must be a declaration of the %tagname.attributes; parameter entity that defines the constrained attributes. For example, the following parameter entity defines a more restricted set of attributes for the <note> element: Draft comment: Kristen Eberlein 12 January 2015 Content needed here The %tagname.content; parameter entity When the content model is constrained, there also must be a declaration of the %tagname.content; parameter entity that defines the constrained content model. For example, the following parameter entity defines a more restricted content model for <topic> , in which either the <abstract> or <shortdesc> element is required. <!ENTITY % topic.content ((%title;), (%titlealts;)?, (%shortdesc; %abstract;), (%prolog;)?, (%body;)?, (%topic-info-types;)*) > Domain constraint modules Domain constraint modules have the following requirements: File names Domain constraint modules should be named using the following format: qualifier domain DomainConstraint.mod where: qualifier is a string that is specific to the constraints module and characterizes it, for example, noSyntaxDiagram or myCompany- . domain is the name of the domain to which the constraints apply, for example, Highlighting or Programming . For example, the file name for a constraint module that removes the syntax diagram from the programming domain might be noSyntaxDiagramProgrammingDomainConstraint.mod . Entity name and value The constraint module SHOULD contain a declaration for a text entity with the following name: domain Domain-constraints where domain is the name of the domain to which the constraints apply, for example, Highlighting or Programming . The value of the text entity MUST use the following format: ( inheritance-hierachy qualifier domain Domain-c) where: inheritance-hierachy is the specialization hierarchy, for example, topic hi-d . qualifier is a string that is specific to the constraints module and characterizes it, for example, noSyntaxDiagram or myCompany- . domain is the name of the domain to which the constraints apply, for example, Highlighting or Programming . The literal -c indicates that the name is the name of a constraint. For example, the following text entity provides the declaration for a constraint module that restricts the highlighting domain: <!ENTITY HighlightingDomain-constraints (topic hi-d basic-HighlightingDomain-c) > Parameter entity When the set of extension elements are restricted, there must be a parameter entity that defines the constrained content model. For example, the following parameter entity restricts the highlighting domain to <b> and <i> : <!ENTITY % HighlightingDomain-c-ph b i > Integrating constraint modules into document type shells For information about how to integrate constraint modules into DTD-based, document type shells, see DTD document-type shell: Coding requirements -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)