OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  My take on generalization

    Posted 10-17-2022 14:47
    As we’ve said several times, the spec should not set out rules for how processors should perform generalization. According, I think we can remove most of the generalization content in chapter 9 other than 8.4.1, “Overview of generalization”.   I think we do need to review 8.4.4 “Attribute generalization” and see if there is content that should be added to 7.4.5 “Conditional processing attribute values with groups”. And we need to ensure that <end-flag> and any attributes topic link to the appropriate target for explaining the generalized attribute syntax.   I think that all other references to generalization in the spec can stand as is.   Topic Content Notes 2.4 Specialization terminology [ generalization ] The process by which a specialized element is transformed into a less-specialized ancestor element or a specialized attribute is transformed into a less-specialized ancestor attribute. The original specialization-hierarchy information can be preserved in the generalized instance; this allows the original specialized type to be recreated from the generalized instance.   [specialization] (1) The act of defining new element or attribute types as a semantic refinement of existing element or attribute types (2) An element or attribute type that is a specialization of a base type (3) A process by which a generalized element is transformed into one of its more specialized element types or a generalized attribute is transformed into a more specialized attribute.   6.4.12 Processing key references to generate text or link text [ Generalization of effective content:] When the effective content for a key reference element results in invalid elements, those elements SHOULD be generalized to produce a valid result.   For example, <keytext> in the key definition might use a domain specialization of <keyword> that is not valid in the key reference context, in which case the specialized element is generalized to <keyword>. If the generalized content is also not valid, a text equivalent is used instead. For example, <keytext> might include <ph> or a specialized <ph> in the key definition, but neither of those are valid as the effective content for a <keyword>. In that case, the text content of the <ph> is used.   7.3.2 The @conaction attribute The target element can be more general than the source. For example, it is legal to push a <step> element to replace a general list item (<li>); the <step> element should be generalized back to a list item during the process.   7.3.3 The @conrefend attribute As with @conref, if the @conrefend references a more specialized version of the referencing element, applications should generalize the target when resolving.   7.3.7 Processing conrefs When content is reused between two documents with different domains or constraints, it is possible for the reused content to include domain extensions that are not defined for the new context, or to include elements that would be constrained out of the new context. When pulling or pushing content with the conref mechanism, processors resolving conrefs SHOULD tolerate specializations of valid elements. Processors MAY generalize elements in the pushed or pulled content fragment as needed for the resolving context.   7.3.8 Processing attributes when resolving conrefs If the referenced element has a @conref attribute specified, the above rules should be applied recursively with the resolved element from one referencing/referenced combination becoming one of the two elements participating in the next referencing/referenced combination. The result should preserve without generalization all elements that are valid in the originating context, even if they are not valid in an intermediate context.   7.4.5 Conditional processing attribute values with groups Grouped values are intended to support situations where a metadata attribute applies to multiple specialized subcategories. For example, if content is classified into two distinct types of product, those distinct types can become named groups within the @product attribute. The grouping syntax exactly matches the syntax used for generalized attributes, making it valid inside @props and any attribute specialized from @props, including those integrated by default in the OASIS-provided document-type shells: @audience, @deliveryTarget, @platform, @product, @otherprops.   8.1 Overview of DITA extension facilities DITA content that uses specializations can be treated as, or converted to, unspecialized markup through the process of generalization . The information about the original specialized form can be retained.   8.6.2 Expansion module rules There are certain rules that apply to the design and implementation of expansion modules. These rules all stem from the requirement that the content model of a specialized element must be consistent with the content model of the specialization base. After generalization , the content model of an element affected by an expansion module must match the original content model for that element.   [Ordinality of expanded elements] When a DITA topic affected by this expansion module is generalized , the resulting markup would be valid; the content model of <ol> would be respected.   1 <endflag> Mentions “ generalized attribute syntaz” The attributes topics often link to the topic on generalized attributes.   Best, Kris   Kristen James Eberlein Chair, OASIS DITA Technical Committee Owner, Eberlein Consulting LLC kris@eberleinconsulting.com Skype: kriseberlein; voice: +1 (919) 622-1501