[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Updated "DTD: Coding requirements for constraint modules" topic
My primary concern about using
normative language about file naming conventions is that I think
it might be be contrary to OASIS directives about the usages of
RFC-2119 terminology.
From the OASIS directives: "Keywords identify the requirements for conforming to a specification or standard. RFC 2119 gives the following guidance on keywords (called "imperatives") Imperatives of the type defined in this memo must be used with
care and sparingly. In particular, they MUST only be used
where it is actually required for interoperation or to limit
behavior which has potential for causing harm (e.g., limiting
retransmisssions) For example, they must not be used to try to
impose a particular method on implementors where the method is
not required for interoperability. [RFC2119]" Note the content that I have highlighted in bold text. We can discuss this at today's TC meeting; I'm also going to
reach out to OASIS for assistance. Best,
On 1/27/2015 9:34 AM, Eliot Kimber wrote:Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) I don't think it helps to move the naming conventions out of the main part of the spec. Having them be should statements is sufficient. The whole point of the naming conventions is to support the general DITA architectural practice of having consistent implementation patterns in order to foster interchange of *knowledge* as well as interoperability of content. While the naming conventions are somewhat arbitrary, they are arbitrary for a reason, namely so that you have some hope of predicting what a given module is about based on its name. It's unfortunate that in DITA 1.2 we didn't properly enforce our own rules, but that doesn't mean we should just throw them out entirely. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/27/15, 6:33 AM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote: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: qualifierTagnameConstraint.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 qualifierTagname-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: qualifierdomainDomainConstraint.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: domainDomain-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 qualifierdomainDomain-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 <shell-dtd-coding-reqs.html> -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com <http://www.eberleinconsulting.com> +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]