conref - improved specialization support
Longer description
Conref currently
checks both class and domains attributes to ensure an exact match between
allowed semantics in the source and target elements.
In order to allow
more flexibility the following improvements are proposed:
- Allow domain subsets as well as exact matches. For example, if the referencing
element allows domains "x y z" and the referenced element allows domains "x
z" then the conref should be considered valid.
- Allow matches to more specialized elements. For example, if the referencing
element is a list item (class "topic/li") then it should be valid to conref
any element specialized off of list item (for example <step class="+ topic/li
task/step ">).
If the intermediate result needs to be validated or downstream
processes are not specialization-aware, then the conref processor will need
to generalize on the fly.
If the intermediate result does not need to
be validated, and downstream processes are specialization-aware, then the
conref processor should be able to copy the target without generalizing, even
though the result is not technically valid, since it will process correctly
based on the class attribute. This does present the danger of a process attempting
to work with a specialized element in a context it doesn't expect, which could
cause breakages - so this approach has dangers. As a contrived example, if
someone created specialized processing for <stepresult> that grabbed the
text from the preceding <cmd>, the processing will fail when the <stepresult>
is found somewhere else where the <cmd> is not available. So not sure if
we can safely recommend this approach in production systems.
- Allow matches to more specialized domains. For example, if the referencing
element allows "(topic x) (topic y)" and the referenced element allows "(topic
x myx)" then the match should be allowed, with any elements from the specialized
domain being either generalized or copied as-is, per treatment for specialized
elements in the previous item.
Scope
Major if we support generalization
on the fly; potentially minor if not
Use Case
- Domain checking: teams can now define common resource files for use across
many different groups even with different domain usage, as long as the common
file contains only common denominator domains.
- Specialization handling: teams can now reuse even specialized content
across specialization boundaries. For example, the <context> element from
a task could be pulled into a concept as a regular section.
- Specialization handling also allows teams to define different rules or
semantics in the topics they reuse from, without having to introduce equivalent
semantics everywhere they reuse. For example, a team might want to manage
legal warnings in a special controlled topic, and explicitly avoid providing
the domain elsewhere. With the new capability, authors would be able to reuse
from a general <note> to the special legal <legalwarning>, but would
not be able to author a <legalwarning> directly outside of its special
topic.
Technical Requirements
Changes to
validating conref processors would be required.
Costs
Development time for generalization
on the fly: ca. 1 month
Development time for other aspects: ca. 1 week
Benefits
More flexible conref without
losing robustness of transformation. We are identifying more valid cases,
and thus making conref more useful.
Time Required
Guessing 3 meetings
of 1 hour each to determine final design.