Re: Action Item: Implications for key definition subelements for topicre

Follow up to my initial analysis.

If we take the TC’s decision that the correct behavior is to apply the topicref-to-topic cascading rules to the cascade from the referenced keydef to the referencing topicref in Denis’ examples, then the effective results are as shown below.

In reviewing the 2.0 language for map-to-topic metadata element cascading, the rules appear to be underspecified (the current 2.0 language appears to be the same as the 1.3 language).

The section 5.3.2 Reconciling topic and map metadata elements says only:

<quote>

How does it apply to the topic?

This column describes how the metadata specified within the <topicmeta> element interacts with

the metadata specified in the referenced topic. *In most cases*, the properties are additive. (Emphasis mine).

</quote>

Note the “In most cases”. The table that follows only says “add to the topic” for each element that cascades—it does not say anywhere that I can find whether or not values are combined. The reference entry for <keywords> does not address cascading behaviors.

Thinking about it now, I think I would want and expect keywords values to be combined, such that any in-topic keywords or index entries are combined with any imposed keywords or index entries, on the principle that values in the topic represent invariant properties of the topic that should apply in all use contexts. I have reflected that behavior in the example below.

<map><title>Keywords cascading/combining via keyref</title>

<!-- Resource-only keydef that has a <keywords> element with a <keyword> element.

If this was a normal-role topicref then topic topic-01.dita would have the effective

<keywords> value of “installation” imposed on to it by the normal map-to-topic

metadata cascade rules for <keywords>.

-->

<keyword>installation</keyword>

</keywords>

</topicmeta>

</keydef>

<!-- keywords element cascaded from the keydef for key “topic-01”

by application of topicref-to-topic cascading rules.

-->

<keyword>installation</keyword>

</keywords>

</topicmeta>

</topicref>

<!-- keywords element cascaded from the keydef for key “topic-01”

by application of topicref-to-topic cascading rules.

If we accept that topicref-to-topic elements are combined, then

the keywords element from the keydef is combined with the

empty keydef in the original topicref.

-->

<keyword>installation</keyword>

</keywords>

</topicmeta>

</topicref>

</map>

For both uses of topic “topic-01.dita”, the effective <keywords> value is the same (keyword “installation”) by normal application of the topicref-to-topic metadata element cascading rules.

Cheers,

Eliot

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

From: Eliot Kimber <eliot.kimber@servicenow.com>
Date: Tuesday, September 26, 2023 at 12:49 PM
To: dita <dita@lists.oasis-open.org>
Subject: Re: Action Item: Implications for key definition subelements for topicref-to-topicref key references

Denis’ initial question actually involves two different cases: one where the referencing keydef does not have any <keywords> element and one where it has an empty <keywords> element. That raises the question of whether these two cases would result (or should result) in a different effective value for <keywords> in the referencing topicref.

In addition, the 2.0 spec is not 100% clear whether this case should follow the topicref-to-topicref (within-map) cascading and combination rules or the topicref-to-topic cascading and combination rules.

Here is an example that I think reflects Denis’ use cases:

<map><title>Keywords cascading/combining via keyref</title>

<!-- Resource-only keydef that has a <keywords> element with a <keyword> element.

If this was a normal-role topicref then topic topic-01.dita would have the effective

<keywords> value of “installation” imposed on to it by the normal map-to-topic

metadata cascade rules for <keywords>.

-->

<keyword>installation</keyword>

</keywords>

</topicmeta>

</keydef>

<!--This topicref makes a key reference to “topic-01”. It has

<topicmeta> but no <keywords> element.

-->

</topicref>

<!-- This topicref also makes a key reference to “topic-01”. It has

a <keywords> element that has no child <keyword> elements.

-->

</topicmeta>

</topicref>

</map>

The question is:

For each of the <topicref> elements, what is the effective value of <keywords> following key resolution and metadata cascading and combining?

There seem to be two defensible answers this question, depending on whether the rules for topicref-to-topicref metadata cascading applies or whether the rules for topicref-to-topic cascading applies. For the specific case of <keywords> the results are different.

The relevant specification language is in two places: 6.4.11, Processing key references on <topicref> elements and 5.3.2, Reconciling topic and map metadata elements.

6.4.11 says:

<quote>
Combining metadata

Content from a key-defining element cascades to the key-referencing element following the rules for

combining metadata between maps and other maps and between maps and topics.

The combined attributes and content cascade from one map to another or from a map to a topic, but

this is controlled by existing rules for cascading, which are not affected by the use of key references.

</quote>

The ambiguity here is “the rules for combining metadata between maps and other maps and between maps and topics.” It’s not clear from this statement if the cascade from topicref to topicref via keyref should follow the topicref-to-topicref rules or the topicref-to-topic rules.

The rules for cascading of <keywords> is defined in section 5.3.2, in Table 1: <topicmeta> elements and their properties:

For the column “How does it apply to the topic” the entry for <keywords> says “Add to the topic” but for the column “Does it cascade to child <topicref> elements?” is says “No”.

Therefore, if we interpret a keyref from a topicref to a topciref as using the within-map cascading rules, <keywords> clearly does not cascade from the referenced keydef to the referencing topicref.

However, if we interpret the referencing topicref as acting like a topic (“and between maps and topics”) then the <keywords> element would be added to the first topicref in the example above (because there is no <keywords> element) but not to the second, which has a <keywords> element.

In my reading of the sections on metadata cascading generally, I do not see anything about the combining of metadata elements, only metadata attributes that take multiple values. Thus it’s not entirely clear what the intent is for something like <keywords> that can take multiple values—do they combine when cascading from topicrefs to topics or do they not?

It makes sense to me that <keywords> would cascade from a referenced keydef to its referencing topicref (and, by implication, to the topic ultimately referenced), that is, the same result you would get if the referenced keydef was a normal-role topicref.

it also makes sense to me that specifying <keywords> in the referencing topicref would prevent cascading from the referenced keydef, as otherwise you’d have no way to override keywords otherwise cascaded from the referenced keydef (meaning that you would be unable to impose different keywords on the same topic used in different contexts in a map).

This also points up that there’s a little bit of a potentially confusing back-and-forth with the metadata, where the topicref-to-topicref cascading is in the direction from referenced keydef to referencing topicref but then is from the direction of referencing topicref to referenced topic, reflecting the effective metadata of the referencing topicref after applying cascading rules between the referenced keydef and referencing topicref:

Here the cascading process is:

Cascade metadata from the <keydef> to the <topicref>, possibly resulting in the <topicref> having an effective <keywords> element cascaded from the <keydef>
Cascade metadata to topic “topic-01.dita”, reflecting the effective metadata of the topicref.

Conceptually, we can imagine that the chain of topicrefs from the initial <topicref> to the topicref that references the topic are “collapsed” into a single effective topicref that reflects the cascading of metadata from the end of the chain to the start of the chain. This effective topicref then imposes its effective metadata onto the target topic just as it would if it had been directly authored as a single topicref.

As a TC we need to decide whether the metadata cascade from referenced keydef to referencing topicref uses the topicref-to-topicref rules or the topicref-to-topic rules or some new rule we haven’t defined.

My vote at the moment is that it should be the topicref-to-topic rules, reflecting the fact that the initial topicref serves as a proxy for the ultimately referenced topic and that with this behavior the result can be the same as if the keydef was a normal-role reference to the topic.

In addition, it may be necessary to clarify the metadata combining rules for the <keywords> case: does it act like an attribute that takes multiple values or is it always just a “cascade if no <keywords> element is present in referencing topicref”?

If combining applies, that implies that the @combine attribute also applies, which doesn’t seem to be accounted for in the current 2.0 language and is probably a level of complication we’ve actively avoided to date.

Cheers,

Eliot

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

From: Eliot Kimber <eliot.kimber@servicenow.com>
Date: Tuesday, September 19, 2023 at 10:33 AM
To: dita <dita@lists.oasis-open.org>
Subject: Action Item: Implications for key definition subelements for topicref-to-topicref key references

Here is my proposed response to Denis Troaca’s question about cascading of <keywords> from a referenced topicref to a referencing topicref:

Denis Troaca asks:

<quote>

According to DITA Specification(https://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/example-keydef-with-keyref.html), if we have a keydef element with a keyref to another key, the first key should pull resources from the second if they are not already present in the initial keydef. Does this rule also apply to child elements of elements within that keydef?

Example:Â

The initial keydef contains a "topicmeta" element with no "keywords" elements or containsÂa "topicmeta" with a "keywords" but no "keyword" elementsÂinside and the referenced keydef has a "topicmeta" with "keywords" and "keyword" elements. Does the initial keydef pull the "keyword" from the referenced keydef or does it keep its empty "topicmeta" element?

</quote>

For this case, the DITA 2.0 spec as of 19 September 2023 says in section 6.4.11, “Processing key references on <topicref> elements”:

<quote>

Combining metadata

Content from a key-defining element cascades to the key-referencing element following the rules for

combining metadata between maps and other maps and between maps and topics.

The combined attributes and content cascade from one map to another or from a map to a topic, but

this is controlled by existing rules for cascading, which are not affected by the use of key references.

</quote>

Thus the existing metadata cascade rules apply, where the referencing topicref is the effective child of the referenced topicref.

Given that, the entry for <keywords> in the table in section 5.3.2, “Reconciling topic and map metadata elements” determines the behavior. This entry indicates that <keywords> does *not* cascade from topicref to topicref.

Thus, in this case, the keywords in the referenced topicref do not cascade to the referencing topicref.

Given Denis’ original example, the effective value for <keywords> in the initial keydef is an empty <keywords> element.

Cheers,

Eliot

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

dita message