@domains
attribute rules and syntax
The @domains
attribute enables processors to
determine whether two elements or two documents use compatible domains. The attribute is
declared on the root element for each topic or map type. Each structural, domain, and constraint
module defines its ancestry as a parenthesized sequence of space-separated module names; the
effective value of the @domains
attribute is composed of these parenthesized
sequences.
Document type shells collect the values that are provided by each module to construct the
effective value of the @domains
attribute. Processors can examine the
collected values when content from one document is used in another, in order to determine
whether the content is compatible.
For example, when an author pastes content from one topic into another
topic within an XML editor, the application can use the @domains
attribute to
determine if the two topics use compatible domains. If not, copied content from the first
topic might need to be generalized before it can be placed in the other topic.
The @domains
attribute serves the same function when an
element uses the @conref
attribute to reference a more specialized version of
the element. For example, a <note>
element in a concept topic conrefs a
<hazardstatement>
element in a reference document. If the hazard
statement domain is not available in the concept topic, the
<hazardstatement>
element is generalized to a
<note>
element when the content reference is resolved.
Syntax and rules
Each domain and constraint module MUST provide a value for use by the @domains
attribute. Each
structural vocabulary module SHOULD
provide a value for use by the @domains
attribute, and it MUST do so when it has a dependency on
elements from any module that is not part of its specialization ancestry.
Values provided for the @domains
attribute values are
specified from root module (map or topic) to the provided module.
- structural modules
-
The value of the
@domains
attribute includes each module in the specialization ancestry:'(', topic-or-map, (' ', module)+, ')'
For example, consider the
<glossentry>
specialization, in which the topic type is specialized to the concept type, and the concept type is specialized to glossentry. The structural module contribution to the value of the@domains
attribute for the glossentry structural module is(topic concept glossentry)
. - structural modules with dependencies
-
Structural modules can directly reference or specialize elements from modules that are outside of their specialization ancestry. They also can define specialized elements that reference specialized attributes. In these cases the structural module has a dependency on the non-ancestor module, and the structural module contribution to the value of the
@domains
attribute MUST include the names of each dependent, non-ancestor module.Dependencies are included in the value of the@domains
attribute following the name of the structural module with the dependency on the non-ancestor module. Domain or attribute modules are appended to the name of the structural module with the dependency on the non-ancestor module, or to previous dependencies, separated by "+". Dependencies on structural specialization modules are appended to the name of the structural module with the dependency on the non-ancestor module, or to previous dependencies, separated by "++". The syntax is the same as for other structural modules, except that added modules can include these dependencies:'(', topic-or-map, (' ', module-plus-optional-dependency-list)+, ')'
When the structural module is included in a document-type shell, all dependency modules also are included along with their own
@domains
values.For example, the cppAPIRef structural module is specialized from reference, which is specialized from topic. The cppAPIRef module has a dependency on the cpp-d element domain and on the compilerTypeAtt-d attribute domain. The dependencies are listed after the name ofcppApiref
:(topic reference cppApiRef+cpp-d+compilerTypeAtt-d)
Similarly, a codeChecklist structural module is specialized from reference, which is specialized from topic. The codeChecklist module has a dependency on the pr-d domain and on the task structural specialization. Again, the dependencies are listed after the name ofcodeChecklist
. The pr-d domain and the task module each contribute their own values, so taken together these modules contribute the following values:(topic reference codeChecklist+pr-d++task) (topic pr-d) (topic task)
- element domains
-
The value includes the structural type ancestry and, if applicable, the domain module ancestry from which the domain is specialized:
'(', topic-or-map, (' ', domain-module)+, ')'
- structural constraint modules
-
The value includes the structural type ancestry followed by the name of the constraint domain:
'(', inheritance-hierarchy qualifierTagname-c, ')'
where:
- inheritance-hierarchy 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.
For example, the strictTaskbody constraint applies to the task module, which is specialized from topic, resulting in the following value:
(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. - inheritance-hierarchy is the
specialization hierarchy, for example,
- domain constraint modules
-
The value includes the specialization ancestry followed by the name of the constraint domain:
'(', inheritance-hierachy qualifierdomainDomain-c ')'
where:
- inheritance-hierarchy 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, a domain constraint module that restricts the highlighting domain includes a value like the following:
(topic hi-d basic-HighlightingDomain-c)
- inheritance-hierarchy is the specialization hierarchy, for
example,
- attribute domains
-
The value uses an "a" before the initial parenthesis to indicate an attribute domain. Within the parenthesis, the value includes the attribute specialization hierarchy, starting with
@props
or@base
:'a(', props-or-base, (' ', attname)+, ')'
For example, the
@mySelectAttribute
specialized from@props
results in the following value:a(props mySelectAttribute)
Example: Task with multiple domains
In this example, a document-type shell integrates the task structural module and the following domain modules:
Domain | Domain short name |
---|---|
User interface | ui-d |
Software | sw-d |
Programming | pr-d |
The value of the @domains
attribute includes one value from each module;
the effective value is the following:
domains="(topic task) (topic ui-d) (topic sw-d) (topic pr-d)"
If the document-type shell also used a specialization of the programming domain that
describes C++ programming (with a short name of "cpp-d"), the new C++ programming domain
would add an additional value to the @domains
attribute:
domains="(topic task) (topic ui-d) (topic sw-d) (topic pr-d) (topic pr-d cpp-d)"
Note that the value for the @domains
attribute is not authored; Instead,
the value is defaulted based on the modules that are included in the document type
shell.