@domains attribute rules and syntax

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)