The DITA specification uses specific notation and terms
to define the components of the DITA standard. This terminology
is not intended to serve as a tutorial or provide a user-friendly
introduction to the DITA standard.
Notation
This specification
uses specific conventions for mentions of element and attribute
types:
- Attribute types
- Attribute names may be preceded by @ to distinguish them from
elements or surrounding text, for example, the @props
or the @class attribute.
- Element types
- When elements are named outside of a list, they may be delimited
with angle brackets (< and >) to distinguish them
from surrounding text, for example, the <keyword>
and the <prolog> element.
In general, the unqualified use of the
term map or topic can be interpreted
to mean "a <map> element and any specialization of a <map> element
" or "a <topic> element or any specialization of a <topic>
element."
Conformance terminology
The
key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.
- MUST
- This word, or the terms "REQUIRED" or "SHALL", mean that the definition
is an absolute requirement of the specification
- MUST NOT
- This phrase, or the phrase "SHALL NOT", mean that the definition
is an absolute prohibition of the specification.
- SHOULD
- This word, or the adjective "RECOMMENDED", mean that there may
exist valid reasons in particular circumstances to ignore
a particular item, but the full implications must be understood
and carefully weighed before choosing a different course
- SHOULD NOT
- This phrase, or the phrase "NOT RECOMMENDED" mean that there may
exist valid reasons in particular circumstances when the
particular behavior is acceptable or even useful, but
the full implications should be understood and the case carefully
weighed before implementing any behavior described with
this label.
- MAY
- This word, or the adjective "OPTIONAL", mean that an item is truly
optional. One vendor may choose to include the item because
a particular marketplace requires it or because the vendor
feels that it enhances the product while another vendor may omit the
same item. An implementation which does not include a
particular option MUST be prepared to interoperate with
another implementation which does include the option, though
perhaps with reduced functionality. In the same vein an implementation
which does include a particular option MUST be prepared
to interoperate with another implementation which does
not include the option (except, of course, for the feature the option
provides.
Basic DITA terminology
The
following terminology is used to discuss basic DITA concepts:
- DITA attribute type
- An attribute type that is one of the following:
- One of the base attribute types that are defined by the DITA specification
- A specialization of the either the @base or @props attribute
- DITA document
- An XML document that conforms to the requirements of this specification.
A DITA document must have as its root
element one of the following elements:
- <map> or a specialization of the <map> element
- <topic> or a specialization of the <topic> element
- <dita>, which cannot be specialized but which allows documents
with multiple sibling topics
- DITA document type
- A unique set of structural modules, domain modules, and constraint
modules that taken together provide the XML element and
attribute declarations that define the structure of DITA
documents. DITA document types normally are implemented using DITA
document-type shells.
- DITA document-type shell
- A set of DTD or XSD declarations that implement a DITA document
type by using the rules and design patterns that are included
in the DITA specification. A DITA document-type shell
includes and configures one or more structural modules, zero or more
domain modules, and zero or more constraint modules. With
the exception of the optional declarations for the <dita>
element and its attributes, DITA document-type shells do
not declare any element or attribute types directly.
- DITA element
- An XML element instance whose type is a DITA element type. DITA
elements must exhibit a @class attribute that has a value
that conforms to the rules for specialization hierarchy
specifications.
- DITA element type
- An element type that is one of the following:
- One of the base element types that are defined by the DITA specification
- A specialization of one of the base element types
A DITA element type is declared in exactly one vocabulary module.
DITA element types may only exhibit attributes that are
DITA attribute types.
- Map instance
- An occurrence of a map type in a document.
- Map type
- An element type that defines a set of relationships among topic
instances. The map type provides the root element and,
through the contained element types, the substructure
for the map instances. The map substructure provides hierarchy, group,
and matrix organization of references to topic instances.
- Structural type instance
- An occurrence of a topic type or a map type in a document.
- Topic instance
- An occurrence of a topic type in a document.
- Topic type
- An element type that defines a complete unit of content. The topic
type provides the root element for the topic and, through
the contained element types, the substructure for the
topic instances. The root element of the topic type is not necessarily
the same as the root element of a document type; document
types may nest multiple topic types and may also declare
non-DITA wrapper elements as the root element for compatibility with
other processes.
Specialization terminology
The
following terminology is used to discuss DITA specialization:
- Base content model
- The content model of a DITA element before specialization or the
application of constraints or extensions.
- Base type
- An element or attribute type that is not a specialization. All
base DITA types are defined by the DITA specification.
- Extension element
- Within a vocabulary module, an element type that can be extended,
replaced, or constrained for use in a DITA document type.
- Generalization
- The process by which a specialized element is transformed into
a less-specialized ancestor-element type or a specialized
attribute is transformed into a less-specialized ancestor
attribute. The original specialization-hierarchy information may be
preserved in the generalized instance, thus allowing the
original specialized type to be recreated from the generalized
instance.
- Restricted content model
- For a DITA element type, a content model that has been restricted
from the base content model for the element type by one
(or more?) of the following mechanisms:
- Removing optional elements
- Requiring optional elements
- Ordering of unordered elements
- Restricting repeatable (but optional) elements from repeating
Content models may be restricted through the use of constraint
modules or through specialization.
- Selective domain extension
- An extension that replaces a extension element with element types
that are defined in an domain module, thus making the
base type unavailable in the DITA document-type shell
that configures the extension.
- Specialization
- (1) The act of defining new element or attribute types as a semantic
refinement of existing element or attribute types
- (2) An element or attribute type that is a specialization of a
base type
- (3) A process by which a generalized element is transformed into
one of its more specialized element types or a generalized
attribute is transformed into a more specialized attribute.
- Specialization hierarchy
- The sequence of element or attribute types, from the most general
to most specialized, from which a given element or attribute
type is specialized. The specialization hierarchy for
a DITA element is formally declared through its @class attribute.
- Specialization parent
- For a given DITA element type, the most specialized of its ancestors
in its specialization hierarchy.
- Specialized attribute type
- An attribute type that is defined as a semantic refinement of
another attribute type. The attribute type be specialized
from either the @base or @props attribute, and its value
must be a subset of or identical to the values allowed by the original
attribute type.
- Specialized element type
- An element type that is defined as a semantic refinement of an
existing element type. The content allowed by the specialized
element type must be a subset of or identical to the content
allowed by the original element type. Within a DITA document, all
specialized element types must be refinements of one of
the base element types, with the exception of elements
that are used in the context of <foreign> or <unknown>
elements.
- Structural type
- A topic type or map type.
DITA modules
The following
terminology is used to discuss DITA modules:
- Attribute domain module
- A domain module that defines exactly one specialization of either
the @base or @props attribute.
- Constraint module
- A set of declarations that impose additional constraints onto
the element or attribute types that are defined in a specific
vocabulary module.
- Domain module
- A set of element types or an attribute type that supports a specific
subject or functional area. Element types or attribute
types in a domain can be integrated with topic types or
map types to enhance semantic support for particular kinds of content.
For example, the structural type <topic> declares the <keyword>
element; when integrated with a domain for describing
user interfaces, new keyword specializations (such as <wintitle>)
become available wherever <keyword> was allowed in the
original structural type.
- Element domain module
- A domain module that defines one or more element types for use
within maps or topics.
- Map module
- A structural module that defines a single map type.
- Structural module
- A vocabulary module that defines exactly one top-level map type
or topic type. Structural modules may also
define specializations of elements from domain modules.
- Topic module
- A structural module that defines a single top-level topic type.
- Vocabulary module
- A uniquely-named unit of element type or attribute type declaration.
There are two types of vocabulary modules: structural
modules and domain modules. For a given map type, topic
type, or domain, there is exactly one vocabulary module that defines
it.
Linking and addressing terms
The
following terminology is used to discuss linking and addressing terms:
- Key
- An identifier defined by a DITA key-defining element. A key is
bound to one or more of the following items:
- The resource addressed by the <topicref> element or the specialization
of a <topicref> element
- The element contained with the <topicmeta> element of the <topicref>
element or the specialization of a <topicref> element
- Key definition
- A <topicref> element or specialization of a <topicref> element
that specifies the @keys attribute and defines one or
more key names.
- Key resolution context
- The root map that establishes the context for resolving key references.
For a given key-resolution instance, there is at most
one root map that defines the effective value of the key
space, as determined by the key definition precedence rules..
- Key space
- The effective set of unique key names that are defined by a given
key resolution context. Within a given key resolution
context, a key name has at most one binding.
- referenced element
- An element that is referenced by another DITA element. See also referencing element.
- Example
The following code sample is from the
installation-reuse.dita topic.
The <step> element that it contains is a referenced element; other
DITA topics reference the <step> element by using the @conref attribute.
<step id="run-startcmd-script">
<cmd>Run the startcmd script that is applicable to your operating-system environment.</cmd>
</step>
- referencing element
- An element that references another DITA element by specifying
an addressing element. See also referenced element and addressing attribute
- @conkeyref attribute
- @conref attribute
- @href attribute
- @keyref attribute
- Example
The following <step> element is a referencing
element. It uses the @conref attribute to reference a <step> element
in the
installation-reuse.dita topic.
<step conref="installation-reuse.dita#reuse/run-startcmd-script>
<cmd/>
</step>
- addressing attribute
- An attribute, such as @conref, @conkeyref, @keyref, and @href,
that can be used to specify an address.
Example
The following figure
illustrates the relationship between a DITA document, its DITA
document-type shell, and the various vocabulary modules that
it uses.
Figure 1. Instances, modules, and declarations