QR code for this page

Powered by Titania Delivery

Specialization

The specialization feature of DITA allows for the creation of new element types and attributes that are explicitly and formally derived from existing types. The resulting specialization allows for the blind interchange of all conforming DITA content and a minimum level of common processing for all DITA content. It also allows specialization-aware processors to add specialization-specific processing to existing base processing.

Specializations are explicitly declared in documents

The specialization feature of DITA defines both a specialization hierarchy declaration syntax used in document instances and a set of document type implementation requirements. The specialization declarations allow processors to determine what set of specializations and associated local constraints a given DITA document uses. The specialization declarations for individual elements and attributes allow processors to determine what the type hierarchies of those elements and attributes are, from which processors can determine the most appropriate (or available) processing to apply.

Specialization enables controlled extension

Specialization allows you 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.

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". However, in most documentation-focused XML applications there is often a clear hierarchy of types. For example, in a technical manual, there might be generic sections and more specialized sections, e.g. "Troubleshooting" or "Assembly Procedures". The presentation of the generic and specialized sections might be identical, but the more specialized sections might have more restrictive constraints or include additional element types relevant only to those section types. While these relationships might be understood by authors and system implementors, the XML standard provides no direct way to express the relationship, to say explicitly "A Troubleshooting section is a generic section and must conform to all requirements of generic sections". Having created the element type <section> and implemented presentation processing for it and then having later created the element type <troubleshooting>, there is no obvious mechanism for having all <troubleshooting> elements automatically get the processing associated with <section> elements. To get that behavior someone has to explicitly update all processors involved to apply <section> processing to <troubleshooting>.

The DITA specialization feature provides a standard mechanism for saying explicitly, using normal XML syntax, "A Troubleshooting section is a generic section and must conform to all requirements of generic sections" and, having said that, makes it possible for generic section processing to be applied to troubleshooting sections with no further effort.

When to use or not use specialization

Specialization is used when new structural types or new domains are needed. DITA specialization can be used when you want to make changes to your design for the sake of increased consistency or descriptiveness or have specific needs for output that cannot be addressed using the current data model. Specialization is not normally used for simply creating different output types, as DITA documents may be transformed to different outputs.

Do not use specialization to simply eliminate unneeded or unwanted element types from specific content models. The content models for element types defined in vocabulary modules can be configured using separately-defined constraint modules without the need to create new specializations. See Constraints.

Use specialization when you are dealing with new semantics (new, meaningful categories of information, either in the form of new structural types or new domains). The new semantics can be encoded as part of a specialization hierarchy, that allows them to be processed by existing specialization-aware transforms or transformed back to more general equivalents ("generalization") for processing by transforms that only understand the unspecialized base types. Use constraints to configure content models and attribute lists without changing semantics.

Types of specialization hierarchy

There are two kinds of specialization hierarchy: one for structural types (with topic or map at the root) and one for domains (with elements in topic or map at their root, or the @props or @base attributes). Structural types define topic or map structures, such as concept or task or reference, which often apply across subject areas (for example, a user interface task and a programming task may both consist of a series of steps). Domains define markup for a particular information domain or subject area, such as programming, or hardware. Each type of vocabulary 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, as appropriate for the domain. In addition, specific structural types may require the use of specific domains.

Specialization of attributes

With structural specializations you can limit the allowed values of attributes defined on the base types of specialized types. You can also define new attributes through domain specializations based off of the @props attribute (for conditional processing) or the @base attribute (for other simple token attributes).

Note

As a general practice, structural specializations should not limit the values of the built-in selection attributes. Use constraint modules to define specific value lists for built-in selection attributes.

Attribute specialization allows you to define new conditional processing attributes that can be used for filtering and flagging (specializations of @props) or new attributes with no existing equivalent that can be managed and generalized in the same way as conditional processing attributes (specializations of @base).

New attributes need to be specialized from either @props or @base:

  • Attributes specialized from @props are recognized as conditional processing attributes
  • Attributes specialized from @base have no existing behavior associated with them
  • Values in specialized attributes should be preserved during generalization and respecialization as for @props
  • While generalized, the attribute values should still be understandable by both general and specialized behaviors, and be treated as equivalent to their specialized form. For example, conditional filtering should work the same way on specialized attributes and on generalized attributes.

In this section:

  1. Vocabulary modules
    Vocabulary modules are atomic units of XML vocabulary definition (element types and attributes). A given DITA element type or attribute is declared in exactly one vocabulary module.
  2. Requirements for specialized element types and attributes
    When you specialize one element from another, or a new attribute from @props or @base, the new element or attribute must obey certain rules in order to be a conforming specialization.
  3. Element type specialization hierarchy declaration (the @class attribute)
    Each DITA element declares its specialization hierarchy as the value of the @class attribute. The @class attribute usually provides a mapping from the element's current name to its more general equivalents, but it can also provide a mapping from the current name to more general and more specialized equivalents. All specialization-aware processing can be defined in terms of @class attribute values without reference to a given element's tagname.
  4. Domain usage declaration (the @domains attribute)
    Structural types must declare the domain vocabulary modules and constraint modules they use. This is done with the @domains attribute, whose value is a sequence of parenthesized module ancestry specifications. The @domains attribute is declared on the root element for each topic or map type. Structural modules should declare their structural ancestry.
  5. Generalization
    Specialized content can be generalized to any ancestor type. The generalization process can preserve information about the former level of specialization to allow round-tripping between specialized and unspecialized forms of the same content.
  6. Attribute generalization
    There is a particular syntax to generalize attributes that have been specialized from the @props or @base attribute. Specialization-aware processors should be able to recognize and process both the specialized and generalized forms of an attribute as being equivalent in their values.
  7. Specializing foreign or unknown content
    Specializing the <foreign> or <unknown> element is an open extension to DITA for the purpose of incorporating standard vocabularies for non-textual content, such as MathML and SVG, as in-line objects. These elements should not be used to include textual content or metadata in DITA documents except where such content acts as an example or display, rather than as the primary content of a topic.
  8. Specialization module coding requirements
    The base DITA element and attribute types may be extended through the creation of new vocabulary modules that define specializations of more-general types.
Parent topic: Configuration, specialization, and constraints

Was this helpful?