@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 of cppApiref:
(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 of codeChecklist. 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)+, ')'
For example, the highlighting domain (specialized from topic) supplies the following value: (topic hi-d). A CPP domain that is specialized from the programming domain, which in turn is specialized from topic, supplies the following value: (topic pr-d cpp-d).
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.

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)

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.