Domain usage declaration (the @domains attribute)
Each structural, element, and attribute domain defines its module ancestry as a parenthesized sequence of space-separated module names from root module to provided module.
For element domains, the group syntax is:
'(', modulename, (' ', modulename)+, ')'
For attribute domains, the group syntax is:
'a(', attname, (' ', attname)+, ')'The module ancestry specifications are added to the effective value of the @domains
attribute to form a set of specifications, one for each domain used by the topic or
map type.
The @domains values for the different module types are as follows:
- structural domains
- The structural type ancestry. For example:
(topic concept glossentry). When a structural domain depends on one or more element or attribute domains, the structural domain's @domains specification must include the domain dependencies following the name of the specialize structural domain, e.g.(topic reference cppApiRef cpp-d compilerTypeAtt-d), here reflecting a topic specialization that depends on two domains, "cpp-d" and "compilerTypeAtt-d".note
The specification of domain dependencies serves in part as a signal to document type shell authors that the domain module must always be integrated along with the structural module. - constraint modules
- The structural type ancestry followed by the name of the constraint domain. For example:
(topic task strictTaskbody-c). - element domains
- The structural type ancestry and, if applicable, the domain module ancestry from which
the domain is specialized. For example:
(topic hi-d)(topic pr-d cpp-d). - attribute domains
- The attribute specialization hierarchy. For example:
a(props mySelectAttribute).
The @domains attribute allows processors to determine whether or not two elements use compatible domains. For example, when pasting content from one topic into another topic within an editor, the editor can use the @domains attribute to determine if the paste target topic's domains are compatible with the paste source topic's domains and therefore whether or not the pasted content needs to be generalized before it can be pasted. Likewise, processors can use the value of the @domains attribute to determine if they have whatever may be necessary to support a particular domain.
The effective value of the @domains attribute is constructed using integration mechanisms specific to each XML document constraint language. Each domain and constraint module must provide a @domains attribute value fragment that can be used by DITA document types to construct the effective @domains attribute value. Each structural vocabulary module should provide a @domains attribute value fragment. See Configuration (Document type shells).
Example: task with multiple domains
<task id="mytask" class="- topic/topic task/task " domains="(topic ui-d) (topic sw-d) (topic pr-d)"> ... </task>
In this example, the task allows the use of elements for describing user interfaces (ui-d), software (sw-d), and also programming (pr-d).
If the document used a specialization of the programming domain to describe C++ programming, the new domain would need a separate entry in the @domains attribute, e.g.:
<task id="mytask" class="- topic/topic task/task " domains="(topic ui-d) (topic sw-d) (topic pr-d) (topic pr-d cpp-d)"> ... </task>
Example: How editing tools and processors can use the @domains attribute
The @domains attribute enables processors to determine whether two elements use compatible domains. For example, when pasting content from one topic into another topic within an editor, the editor can use the @domains attribute to determine if the paste target topic's domains are compatible with the paste source topic's domains and therefore whether or not the pasted content needs to be generalized before it can be pasted. Likewise, processors can use the @domains value to determine if they have whatever may be necessary to support a particular domain.
Another example is when an element references an element that is a more specialized version of the element, for example. a <li> element of concept topic references a <step> element in a task topic. During processing, the <step> element will be generalized back to a <li> element.