DITA Proposed Feature # 17a

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

  1. 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.
  2. 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.
  3. 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.