Preview of 13121 - reuse of elements from structural specializations - with discussion of changed syntax

[Michael Priestley <mpriestl@ca.ibm.com>]

I haven't made the required changes to
existing topics yet, but here's a couple of new topics, combining the rule
discussion for reusing domain specialization elements (from DITA 1.2, but
with syntax changes) and for reusing structural specialization elements
(added for DITA 1.3).

I've made a couple of syntax changes
in the domain attribute since the previous proposal, which will impact
the troubleshooting proposal. I know that's a pain, and I apologize, but
here's why I did it:

- For the domain syntax, as I looked
at the examples and the previously agreed syntax I just couldn't come up
with simple logical generalization rules. I had them for structural but
couldn't replicate with the domain dependencies. So I changed the domain
syntax to be more in line with the structural one: eg (topic concept codeConcept+pr-d).
- For the structural syntax, we were
including the fragment identifier as part of the dependency declaration
- eg (topic troubleshooting+task/steps). But that extra /steps wasn't actually
being used by any of the downstream processing, eg conref or generalization.
So it was just eating up space in the domains attribute, which is already
straining at its character limit. So I eliminated the fragment identifier,
which means you can reuse multiple fragments from the same source (eg,
adding /steps as well as /steps-unordered) without having to add more values
to the domain attribute: eg it just becomes (topic troubleshooting+task)
- But now the two types of dependency
have the same syntax, but need to be treated differently (the discussion
of the difference is in the new topic). So I changed the syntax even further,
so that we could differentiate the structural dependency from a domain
dependency - by using "++" instead of "+": (topic troubleshooting++task)

Other alternatives I looked at:
- Could we identify the domains because
of the naming syntax? Domains typically have -d suffixes. Answer: nope.
"Typically" doesn't cut it - it's a naming convention, not a
requirement. I checked the spec wording.
- Could we use the same +/- syntax we
use in the class attributes to distinguish domains and structural specialization?
IE use "+" for domain dependencies, and "-" for structural
ones? Answer: ick. It would work technically, but (topic troubleshooting-task)
suggests we're removing elements rather than adding them - it might be
more consistent but at the cost of intuitiveness.

So with that out of the way, here's
the actual new spec topic, with changes incorporated - feedback and discussion
welcomed and encouraged:



Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

Title: Sharing elements across specializations

Sharing elements across specializations

The process of specialization allows for easy reuse of elements from ancestor specializations; however, it is also possible to reuse elements from other unrelated specializations, as long as the dependency is properly declared to prevent invalid generalization or conref processing.

A structural specialization can incorporate elements from unrelated domains or other structural specializations by referencing them in the content model of a specialized element. For example, a specialized reference topic could declare a specialized list <apilist> in which each <apilistitem> contains an <apiname> element, which is borrowed from the programming domain. Or a specialized concept topic could declare a specialized <process> section that contains the <steps> elements borrowed from task.

The elements included in this manner must be specialized from ancestor content that is valid in the new context. For example, a specialized element can include the <steps> elements in its content model if it could validly include <ol>, because <steps> is specialized from <ol>. If the reusing and reused specializations share common ancestry, the reused elements must be valid in the reusing context at every level they share in common.

For example, suppose there are two specializations of <task>: <mytask> and <yourtask>. The specializer of <mytask> wants to borrow <yoursteps> from <yourtask> instead of creating their own equivalent specialization. The <yoursteps> element is specialized from <steps> in <task>. The specializer of <mytask> can only include <yoursteps> where <steps> would be allowed; they cannot incorporate it anywhere <ol> is allowed, even though <ol> is in its ancestry, because the two specializations share <task> in their ancestry as well, and we need to maintain the validity of <task> as a generalization target. If we allowed <mytask> to transplant specializations of <steps> anywhere they wanted in the <mytask> model, then <mytask> would cease to be a valid specialization of <task>.

Although a well-designed structural specialization hierarchy with controlled use of domains is still the primary means of sharing and reusing elements in DITA, the ability to also share elements declared elsewhere in the hierarchy allows for situations where relevant markup comes from multiple sources and would otherwise be developed redundantly.

Domain attribute syntax for cross-specialization dependencies

When a structural specialization reuses elements from another structural or domain specialization, it has a dependency on the source specialization module that must be declared in the domains attribute in order for conref and generalization processing to function correctly.

The domains attribute must include a parenthetical _expression_ that lists the ancestry for the current specialization. The final value, for the current specialization, must include the modules it depends on, separated by either a "+" for a dependency on a domain specialization or a "++" for a dependency on another structural specialization.

In addition, it must include a separate parenthetical _expression_ for each reused domain or structural specialization that lists the ancestry of the reused specialization.

Dependency on a domain specialization

For example, a codeConcept specialization could specialize from a concept and include elements from the programming domain. Its ancestry, and the ancestry of the domain it uses, would be declared as:

domains="...(topic concept codeConcept+pr-d) (topic pr-d)"

Dependency on a structural specialization

For example, a checklist specialization could specialize from reference and include elements from task. Its ancestry, and the ancestry of the domain it uses, would be declared as:

domains="...(topic reference checklist++task) (topic task)

Generalization with cross-specialization dependencies

Dependencies across specializations limit generalization targets to those that either preserve the dependency or eliminate them. Some generalization targets will not be valid and should be detected before generalization occurs.

When a structural specialization has a dependency on a domain specialization, then the domain cannot be generalized without also generalizing the reusing structural specialization.

For example, if programming domain elements in codeConcept were generalized to their topic equivalents without also generalizing codeConcept elements, then the places where the content model of a codeConcept element includes programming domain elements would become invalid. However, codeConcept could be generalized to concept or topic, without generalizing programming domain elements, as long as the target document type includes the programming domain.

When a structural specialization has a dependency on another structural specialization, then both must be generalized together to a common ancestor.

For example, if the task elements in checklist were generalized without also generalizing checklist elements, then the checklist content models that referenced task elements would be broken. And if the checklist elements were generalized to topic without also generalizing the task elements, then the task elements would be out of place, since they cannot be validly present in topic. However, checklist and task can be generalized together to any ancestor they have in common: in this case topic.

Generalizing processes should detect invalid generalization target combinations and report them as errors.