Re: [dita] Simplifying specialization rules - the state of the discourse

[Eliot Kimber <ekimber@contrext.com>]

I cannot agree to the term "content model specialization" because what is being done is absolutely not specialization as it has always been defined by the DITA standard.

The best name I can think of is "content model configuration". "Configuration" is the term we've used generally to mean the action of combining things *that already exist* into a working document type. 

The act of configuration has always included:

* Defining document type shells
* Implementing constraints

So adding the ability to configure (or rather, allowing the configuration of) content models and attribute lists of individual elements seems like a natural addition to the set of things that are allowed configuration in DITA 1.x. 

So I would be happy with calling these modules that do constraint or extension "configuration modules", where a configuration module can implement constraints or integrate specializations as it needs to.

I'm not that happy with the term "mix-in" only because the term is generally used in XML to mean what we mean by domains: sets of elements that are basically allowed to occur anywhere through some general extension hook, as distinct from allowing a particular element in a particular place. 

That is, domains, the way they are integrated in DITA 1.x, are inherently "mix-ins" the way that term is used generally in other XML contexts (i.e., TEI, JATS, DocBook). Using it to mean something more restricted in DITA could lead to confusion.

I'm not sure the term "mix-in" really adds anything to the discussion of configuring content models to allow specializations only in specific places in a given content model or attribute list.

Cheers,

E.
--
Eliot Kimber
http://contrext.com
 

ïOn 11/1/20, 9:19 PM, "Chris Nitchie" <dita@lists.oasis-open.org on behalf of cnitchie@gmail.com> wrote:

    I've been working off and on on Issue 15 - Simplifying content model specialization rules. The goals of this proposal are relatively straightforward and broadly agreed upon:

    - You should be able to add elements to individual content models without making them globally available on every element - e.g. add <section-shortdesc>, a specialization of <p>, only within <section>, not everywhere <p> is allowed.
    - You should be able to add attributes to individual elements without making them globally available on every element - e.g. add @cell-purpose as a specialization of @base, but only on <entry> and <stentry>.

    The word I've been playing with is "mix-in." When you want to add an element or an attribute to a specific element, you create a mix-in for that element.

    1. Define a domain that defines the elements you want to add, but don't create the "domain integration" entities as you normally would.
    2. Define a "mix-in" module for the content model(s) and/or attribute list(s) you want to add your element(s) and/or attribute(s) to.
    3. Link both your domain and your mix-in into your doctype shell.

    In implementation, a mix-in is identical to a constraint, except that instead of removing elements from the content model, you're adding them. People have varying degrees of frustration with the word "mix-in" and I'm wide open to suggestions, but it's the best I've been able to come up with so far.

    Kris, Robert, Eliot and I have had a few conversations around this, and while we all agree with the goals, and broadly agree on the mechanics of how we'd implement it, we're at a bit of an impasse for how we frame these things in the spec language.

    The problem is the relationship between mix-ins and constraints. Initially I had no intention of explicitly linking them, but as I wrote the Stage 3 proposal I hit a linguistic snag.

    For various boring technical reasons I won't get into here, if you have two constraints that apply to the same content model or attribute list, you have to combine them into a single constraint module. The same is true if you want to apply multiple mix-ins to the same element; you have to combine them. And it's also true if you want to apply both a mix-in and a constraint to the same element. You have to combine them into one thing.

    What do we call that one thing?

    I came to think that mix-ins and constraints are two sides of the same coin, not just in terms of their implementation details, but also conceptually. They are both modifications of a specific element's content model and/or attribute list. So I coined the term "content model specialization" (again, open to suggestions, I don't love it but couldn't come up with anything better) and started referring to constraints and mix-ins as kinds of content model specialization. And when you need to combine a mix-in and a constraint, you create a new content model specialization that does both.

    It's not a perfect solution. Constraints can do more than just affect a single element - you can globally constrain out whole elements from domains, for example. But it's the best I've been able to come up with to solve this linguistic conundrum.

    Some of the disagreement is over the phrase "content model specialization," and again, somebody, please come up with something better. But I think some also feel very strongly that constraints and mix-ins need to be treated as entirely separate concepts in the spec, and object to the umbrella 'content model specialization' terminology. I just don't know how else to answer that question above - 'what do we call that one thing?' And I have come to think of them as variations on the same concept - modifying a specific element in some way.

    So that's where things stand on Issue 15. Others, feel free to chime in with additional details or context or correction. I look forward to discussing it with the committee on Tuesday.

    Chris