[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
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]