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.
- 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:
- 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" >
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
|
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.