2.1.4.3.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.
Among the purposes of generalization:
- Migration
of content (for example, when retiring an unsuccessful specialization),
- 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),
- Reuse of specialized content in an environment that
does not support one or more of its specializations (which may be thought
of as a special case of round-tripping).
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 DITA document type shell 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.
All DITA documents contain a mix of markup from at
least one structural type and zero or more domains. 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 modules
for each generalization, for example, "generalize from reference to topic".
The generalizer can specify multiple target modules, for example, "generalize
from reference to topic and from ui-d to topic". When the source and
target modules are not supplied, generalization is assumed to be from
all structural types to the base (topic or map), and no generalization
is performed for domains.
The generalizer can also supply the target DITA document
type shell. When the target document type is not supplied, the generalized
document will not contain a reference to a DITA document-type shell.
With the exception of topic nesting constraints, it is possible to generate
a document type shell based on the @class and @domains attributes in
the specialized documents. If the@ domains attribute includes all structural,
domain, and constraint modules used, the @domains attribute alone is
sufficient to enable generation of a document type shell.
A generalization process should be able to
handle cases where it is given:
- Just
source modules for generalization (in which case the designated source
types are generalized to topic or map),
- Just target modules 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 module unspecified
|
Generalize this structural type to its base ancestor
|
Check whether the root element of the topic type matches
a specified source module; generalize to its base ancestor if it does,
otherwise ignore the structural type instance unless it has domains to
generalize.
|
Target module specified
|
Check whether the @class attribute contains the target
module. If it does contain the target, rename the element to the value
associated with the target module. Otherwise, ignore the element.
|
It is an error if the root element matches a specified
source but its @class attribute does not contain the target. If the root
element matches a specified source module and its @class attribute does
contain the target module, generalize to the target module. 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 module 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 module specified
|
Check whether the @domains attribute contains the target
module. If it does, generalize to the target module. Otherwise, skip
the structural type instance unless it is itself a candidate for generalization.
|
It is an error if the @domains attribute matches a
specified source but the domain value string does not contain the target.
If the @domains attribute matches a specified source module and the domain
value string does contain the target module, generalize to the target
module. Otherwise, ignore the structural type instance unless it is itself
a candidate for generalization.
|
For each element in a candidate structural type instance:
Target module 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 module specified
|
Check whether the @class attribute contains the target
module; rename the element to the value associated with the target module
if it does contain the target, otherwise ignore the element.
|
It is an error if the last value in the @class attribute
matches a specified source but the previous values do not include the
target. If the last value in the @class attribute matches a specified
source module and the previous values do include the target module, rename
the element to the value associated with the target module. Otherwise,
ignore the element.
|
preserve the values of all attributes except the @class
and @domains attribute, both of which should be supplied by the target
document type.
Previous Topic: 2.1.4.3.4
Domain usage declaration (the @domains attribute)
Next Topic: 2.1.4.3.6
Attribute generalization
Parent Topic: 2.1.4.3
Specialization
Sibling Topics:
2.1.4.3.1
Vocabulary modules
2.1.4.3.2
Requirements for specialized element types and attributes
2.1.4.3.3
Element type specialization hierarchy declaration (the @class attribute)
2.1.4.3.4
Domain usage declaration (the @domains attribute)
2.1.4.3.6
Attribute generalization
2.1.4.3.7
Specializing foreign or unknown content
2.1.4.3.8
Specialization module coding requirements