GeneralizationSpecialized 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.
The generalization can either be for the purpose of migration (for example,
when retiring an unsuccessful specialization) or for temporary round-tripping
(for example, when moving content through a process that is not specialization
aware and has only been enabled for instances of the base structural type).
When generalizing for migration, the class attribute and domains attribute
should be absent from the generalized instance document so that the default
values in the general DTD or schema will be used. When generalizing for round-tripping,
the class attribute and domains attribute should retain the original specialized
values in the generalized instance document.
Any DITA document can contain a mix of markup from at least one structural
type and zero or more domains. The structural types and domains allowed in
a particular document type are defined by the document type shell.
When generalizing the document, the generalizer may choose to leave a structural
type or domain as-is, or may choose to generalize that type or domain to any
of its ancestors.
The generalizer can supply the source and target for each generalization:
for example, generalize from reference to topic. The generalizer can specify
multiple targets in one pass: for example, generalize from reference to topic
and from ui-d to topic. When the source and target are not supplied, generalization
is assumed to be from all structural types to the base (topic or map), and
no generalization for domains.
The generalizer can also supply the target document type. When the target
document type is not supplied, the generalized document will not contain a
DTD or schema reference. At some time in the future it may be possible to
automatically generate a document type shell and target document type based
on the class and domains attributes in the generalized document.
The generalization process should be able to handle cases where it is given
just sources for generalization (in which case the designated source types
are generalized to topic or map), just targets for generalization (in which
case all descendants of the target are generalized to that target), or both
(in which case only the specified descendants of the target are generalized
to that target).
For each structural type instance, the generalization process checks whether
the structural type instance is a candidate for generalization, or whether
it has domains that are candidates for generalization. It is important to
be selective about which structural type instances to process: if the process
simply generalizes every element based on its class attribute values, an instruction
to generalize "reference" to "topic" could leave an APIReference topic with
an invalid content model, since any elements it reuses from "reference" would
have been renamed to topic-level equivalents.
The class attribute for the root element of the structural type is checked
before generalizing structural types:
| Target and source
| Source unspecified
| Source specified
|
| Target unspecified
| Generalize this structural type to its base ancestor
| Check whether the root element of the topic type matches a specified
source; generalize to its base ancestor if it does, otherwise ignore the structural
type instance unless it has domains to generalize.
|
| Target specified
| Check whether the class attribute contains the target; generalize
to the target if it does, otherwise skip the structural type instance unless
it has domains to generalize.
| If the root element matches a specified source but its class attribute
does not contain the target, emit an error message. If the root element matches
a specified source and its class attribute does contain the target, generalize
to the target. Otherwise ignore the structural type instance unless it has
domains to generalize.
| The domains attribute for the root element of the structural type is checked
before generalizing domains:
| Target and source
| Source unspecified
| Source specified
|
| Target unspecified
| Do not generalize domain specializations in this structural type.
| Check whether the domains attribute lists the specified domain; proceed
with generalization if it does, otherwise ignore the structural type instance
unless it is itself a candidate for generalization.
|
| Target specified
| Check whether the domains attribute contains the target; generalize
to the target if it does, otherwise skip the structural type instance unless
it is itself a candidate for generalization.
| If the domains attribute matches a specified source but the domain
value string does not contain the target, emit an error message. If the domains
attribute matches a specified source and the domain value string does contain
the target, generalize to the target. Otherwise ignore the structural type
instance unless it is itself a candidate for generalization.
| For each element in a candidate structural type instance:
| Target and source
| Source unspecified
| Source specified
|
| Target unspecified
| If the class attribute starts with "-" (part of a structural type)
rename the element to its base ancestor equivalent. Otherwise ignore it.
| Check whether the last value of the class attribute matches a specified
source; generalize to its base ancestor if it does, otherwise ignore the element.
|
| Target specified
| Check whether the class attribute contains the target; rename the
element to the value associated with the target if it does contain the target,
otherwise ignore the element.
| If the last value in the class attribute matches a specified source
but the previous values do not include the target, emit an error message.
If the last value in the class attribute matches a specified source and the
previous values do include the target, rename the element to the value associated
with the target. Otherwise ignore the element.
|
When renaming elements during round-trip generalization, the
generalization process should preserve the values of all attributes. When
renaming elements during one-way or migration generalization, the process
should preserve the values of all attributes except the class and domains
attribute, both of which should be supplied by the target document type.
- Attribute generalization Attributes specialized from props or base can be generalized using a special attribute generalization syntax. Specialization-aware processes should be able to recognize and process both the specialized and generalized forms of an attribute as being equivalent in their values.
- Foreign generalization During generalization, DITA elements are modified based on the class attribute to use the name of an ancestor element. This cannot be done with the contents of a specialized <foreign> element, because the contents are not DITA elements and do not have class attributes.
Parent topic: Specialization in content
Previous topic: Specialization validity
|
