Re: Rework of cascading processing rules

The cascading semantic definitely uses the term “merge” (cascade=”merge”) so I think it’s reasonable to use “merge” and “merged” in this context when talking about the effective values of cascaded properties.

The processing also makes a clear distinction between values that are explicitly specified in the markup (either through grammar-defined defaults or literal attributes in the XML markup), values defined by subject schemes (controlled value specifications), and values that are supplied by processors as effective defaults.

Thus we need a way to clearly distinguish values that are present in the XML as parsed, values that are supplied through subject schemes, and values that are supplied by processors. “directly-specfied” seemed like a clear way to refer to the first case.

The XML standard uses the term “attribute specification” to refer to an attribute in an XML start tag:

The Name-AttValue pairs are referred to as the attribute specifications of the element

(https://www.w3.org/TR/xml/#sec-starttags)

Note that in the context of normal XML processing there is no observable difference between attributes that were present in the input XML markup and attributes defaulted by a grammar in the context of grammar-aware parsing:

When an XML processor encounters an element without a specification for an attribute for which it has read a default value declaration, it must report the attribute with the declared default value to the application.

(https://www.w3.org/TR/xml/#dt-default)

So “specified” or “directly specified” seems like appropriate terminology. Unqualified “specified” seems too generic unless it is clearly bound to the specific meaning of “attribute specification” as given in the XML recommendation. Thus “directly specified” to distinguish from subject-schemed imposed or processor applied values.

But maybe the answer is just to reference the XML terminology and use “attribute specification” or “attribute specifications” where I originally used “directly specified”?

Given that, the ways that a value for a given cascading attribute might be determined are, in priority order:

From attribute specifications (as that term is defined in the XML recommendation)
Imposed by a subject scheme
Set by a processor.

Because there are specific rules based on how a value has been imposed and whether or not a given element has a specified value, we need some terminology we can use for those cases.

As for examples, I need to think about this more but as I implement my own cascading processing (in the context of Python, XQuery, and XSLT resolved map constructors that I use for doing key resolution), but these cases definitely need illustration:

Cascading of single-valued properties
Cascading of multi-value properties as affected by the possible values of @cascade
Cascading of values from map to submap

When submap is not the only source of a value
When submap is the only source of a value.

This is to illustrate the special case that applies to submaps, where normally values on submap <map> elements are ignored except when the <map> element is the only value source.

Cascading of values from maps to topics
Implications for relationship tables (cascading from <relcol> elements to <relcell> elements)

Cheers,

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

From: Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Wednesday, January 4, 2023 at 10:07 AM
To: Eliot Kimber <eliot.kimber@servicenow.com>, dita <dita@lists.oasis-open.org>
Subject: RE: Rework of cascading processing rules

[External Email]

See my comments below.

Best,

Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Eliot Kimber
Sent: Tuesday, December 20, 2022 10:48 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Rework of cascading processing rules

Here’s my current attempt at a non-procedural restating of the rules for cascading:

Within the map tree that results from resolving all map references, content references, and key references, the effective value of an attribute for a given topic reference element is determined by considering both the effective direct value of the attribute and the "merged" value that reflects the effective values of ancestor elements when the effective value of @cascade is merge.

<kje>We are introducing new terminology here: “direct” and “merged” values of attributes – and I would prefer it if we could find a way to avoid doing so.</kje>

The effective direct value of an attribute is determined by the value obtained from the first of the following conditions that applies to the topicref element:

The attribute value is explicitly-specified (default values set in document grammars result in explicitly-specific values following grammar-aware XML parsing).
<kje>Do we need to distinguish between the various ways that an attribute value can be explicitly specified – specified at authoring time, fixed in the grammar files, or defaulted in the grammar files – and what takes precedence? Or is that covered by grammar-aware XML parsing?</kje>
The attribute value default is defined in a controlled value file.

When the effective value of @cascade is merge, the effective merged value is determined by combining any effective direct value with the effective value for the nearest ancestor element that has an effective value (which may reflect any merging of values from ancestors). Values specified on the root elements of submaps are ignored except where the submap's root element is the only ancestor that specifies a value for the attribute. Within reltables, elements are considered to be ancestors of the elements to which they apply, making the effective ancestry of elements then then (nearest to farthest ancestor).

If an element has no effective direct or merged value, the effective value may be supplied by the processor.

<kje>What examples does the spec need to provide in order to explicate these behaviors?</kje>