Specialization

Specialization allows information architects to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance.

Specialization modules enable information architects to create new element types and attributes. These new element types and attributes are derived from existing element types and attributes.

In traditional XML applications, all semantics for a given element instance are bound to the element type, such as <para> for a paragraph or <title> for a title. The XML specification provides no built-in mechanism for relating two element types to say "element type B is a subtype of element type A".

In contrast, the DITA specialization mechanism provides a standard mechanism for declaring that an element type or attribute is derived from an ancestor type. This means that a specialized type inherits the semantics and default processing behavior from its ancestor type. Additional processing behavior optionally can be associated with the specialized descendant type.

For example, the <section> element type is part of the DITA base. It represents an organizational division in a topic. Within the task information type (itself a specialization of <topic>), the <section> element type is further specialized to other element types (such as <prereq> and <context>) that provide more precise semantics about the type of organizational division that they represent. The specialized element types inherit both semantic meaning and default processing from the ancestor elements.

There are two types of DITA specializations:

Structural specialization

Structural specializations are developed from either topic or map types. Structural specializations enable information architects to add new document types to DITA. The structures defined in the new document types either directly use, or inherit from, elements found in other document types. For example, concept, task, and reference are specialized from topic, and bookmap is specialized from map.

Domain specialization

Domain specializations are developed from elements defined within topic or map, or from the @props or @base attributes. They define markup for a specific information domain or subject area. Domain specializations can be added to document-type shells.

Each type of specialization module represents an is a hierarchy, in object-oriented terms, with each structural type or domain being a subclass of its parent. For example, a specialization of task is still a task, and a specialization of the user interface domain is still part of the user interface domain. A given domain can be used with any map or topic type. In addition, specific structural types might require the use of specific domains.

Use specialization when you need a new structural type or domain. Specialization is appropriate in the following circumstances:

• You need to create markup to represent new semantics (meaningful categories of information). This might enable you to have increased consistency or descriptiveness in your content model.
• You have specific needs for output processing and formatting that cannot be addressed using the current content model.

Do not use specialization to simply eliminate element types from specific content models. Use constraint modules to restrict content models and attribute lists without changing semantics.

Modularization is at the core of DITA design and implementation. It enables reuse and extension of the DITA specialization hierarchy.

The DITA XML grammar files are a set of module files that declare the markup and entities that are required for each specialization. The document-type shell then integrates the modules that are needed for a particular authoring and publishing context.

Because all the pieces are modular, the task of developing a new information type or domain is simplified. An information architect can start with existing base types (topic or map)—or with an existing specialization if it comes close to matching their business requirements—and only develop an extension that adds the extra semantics or functionality that is required. A specialization reuses elements from ancestor modules, but it only needs to declare the elements and attributes that are unique to the specialization. This saves considerable time and effort, reduces error, enforces consistency, and makes interoperability possible.

Because all the pieces are modular, it is simpler to reuse different modules in different contexts.

For example, a company that produces machines can use the hazard statement domain, while a company that produces software can use the software, user interface, and programming domains. A company that produces health information for consumers can avoid using the standard domains. Instead, it develops a new domain that contains the elements necessary for capturing and tracking the comments made by medical professionals who review information for accuracy and completeness.

Because all the pieces are modular, new modules can be created and put into use without affecting existing document-type shells.

For example, a marketing division of a company can develop a new specialization for message campaigns and have their content authors begin using that specialization, without affecting any of the other information types that they have in place.

A DITA element type or attribute is declared in exactly one vocabulary module.

The following terminology is used to refer to DITA vocabulary modules:

structural module

A vocabulary module that defines a top-level map or topic type.

element domain module

A vocabulary module that defines one or more specialized element types that can be integrated into maps or topics.

attribute domain module

A vocabulary module that defines exactly one specialization of either the @base or @props attribute.

For structural types, the module name is typically the same as the root element. For example, "task" is the name of the structural vocabulary module whose root element is <task>.

For element domain modules, the module name is typically a name that reflects the subject domain to which the domain applies, such as "highlight" or "software". Domain modules often have an associated short name, such as hi-d for the highlighting domain or sw-d for the software domain.

The name (or short name) of an element domain module is used to identify the module in @class attribute values. While module names need not be globally unique, module names must be unique within the scope of a given specialization hierarchy. The short name must be a valid XML name token.

Structural modules based on topic MAY define additional topic types that are then allowed to occur as subordinate topics within the top-level topic.

For example, a top-level topic type might require the use of subordinate topic types that would only ever be meaningful in the context of their containing type and thus would never be candidates for standalone authoring or aggregation using maps. In that case, the subordinate topic type can be declared in the module for the top-level topic type that uses it. However, in most cases, potential subordinate topics are best defined in their own vocabulary modules.

Domain elements intended for use in topics MUST ultimately be specialized from elements that are defined in the topic module. Domain elements intended for use in maps MUST ultimately be specialized from elements defined by or used in the map module. Maps share some element types with topics but no map-specific elements can be used within topics.

Structural modules also can define specializations of, or reuse elements from, domain or other structural modules. When this happens, the structural module becomes dependent.

There are certain rules that apply to element type specializations.

Characteristics

A specialized element type has the following characteristics:

• A properly-formed @class attribute that specifies the specialization hierarchy of the element
• A content model that is the same or less inclusive than that of the element from which it was specialized
• A set of attributes that are the same or a subset of those of the element from which it was specialized, except for specializations of @base or @props
• Values or value ranges of attributes that are the same or a subset of those of the element from which it was specialized

Namespaces

DITA elements are never in a namespace. Only the @DITAArchVersion attribute is in a DITA-defined namespace. All other attributes, except for those defined by the XML standard, are in no namespace.

This limitation is imposed by the details of the @class attribute syntax, which makes it impractical to have namespace-qualified names for either vocabulary modules or individual element types or attributes. Elements included as descendants of the DITA <foreign> element type can be in any namespace.

There are certain rules that apply to attribute specializations.

A specialized attribute has the following characteristics:

• It is specialized from @props or @base.
• It can be integrated into a document-type shell either globally, which makes it available on all elements, or it can be assigned to specific elements by using an expansion module.
• It does not have values or value ranges that are more extensive than those of the attribute from which it was specialized.
• Its values must be alphanumeric, space-delimited values.
• In generalized form, the values must conform to the rules for attribute generalization.

The specialization hierarchy of each DITA element is declared as the value of the @class attribute. The @class attribute provides a mapping from the current name of the element to its more general equivalents. The @class attribute also can provide a mapping from the current name to more specialized equivalents. All specialization-aware processing can be defined in terms of @class attribute values.

The @class attribute tells a processor what general classes of elements the current element belongs to. DITA scopes elements by module type instead of document type. Examples of module types are topic type, domain type, or map type. This enables document-type developers to combine multiple module types in a single document without complicating transformation logic.

The sequence of values in the @class attribute is important because it tells processors which value is the most general and which is most specific. This sequence is what enables both specialization aware processing and generalization.

<!ATTLIST step         class  CDATA "- topic/li task/step ">

<wintitle class="+ topic/keyword ui-d/wintitle ">A specialized keyword</wintitle>

<windowName class="- topic/keyword task/keyword guiTask/windowname ">...</windowName>

The @specializations attribute enables processors to determine what attribute specializations are available in a document. The attribute is declared on the root element for each topic or map type. Each attribute domain defines a token to declare the extension. The effective value of the @specializations attribute is composed of these tokens.

'@', props-or-base, ('/', attname)+

specializations="@props/deliveryTarget @props/platform @props/product"

specializations="@props/deliveryTarget @props/platform @props/platform/hardwarePlatform @props/product"

You can extend DITA to incorporate standard vocabularies for non-textual content, such as MathML and SVG, as markup within DITA documents. This is done by specializing the <foreign> element.

<!-- ============================================================= -->
<!--                   SVG DOMAIN ENTITIES                         -->
<!-- ============================================================= -->

<!-- SVG elements must be prefixed, otherwise they conflict with
     existing DITA elements (e.g., <desc> and <title>.
  -->
<!ENTITY % NS.prefixed "INCLUDE" >
<!ENTITY % SVG.prefix "svg" >

<!ENTITY % svg-d-foreign
   "svg-container
   "
>

Specialization enables reuse of elements from ancestor specializations. However, it is also possible to reuse elements from non-ancestor specializations.