RE: What does dvrKeyscopePrefix really do?

Robert, your call … Shall we discuss this now or hold until we review branch filtering and the DITAVAL reference domain?

Kris

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Eliot Kimber
Sent: Monday, May 30, 2022 12:44 PM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] What does dvrKeyscopePrefix really do?

I’m updating DITA For Practitioners to reflect DITA 1.3 and 2.0 and as part of that I’m writing a new tutorial step on using branch filtering. In reviewing the spec I realized that dvrKeyscopePrefix appears to be defined in a way that is either surprising or possibly incorrect (or at least not what most/all users would want), so I wanted to raise the issue so that we can at least clarify the language in 2.0 if needed.

The dvrKeyscopePrefix/Suffix elements let you specify a prefix or suffix to add to any keyscopes defined for the branch.

The 1.3 language (which I think is also the current 2.0 language) for dvrKeyscopePrefix is:

Enables a map author to specify a prefix that is added to the start of key scope names for each key scope in the branch. If no key scope is specified for the branch, this can be used to establish a new key scope, optionally combined with a value specified in <dvrKeyscopeSuffix>.

The language I’m focusing on here is “each key scope in the branch”, which could either be read as “the values of the @keyscope attribute on the branch-defining element” or “The key scopes defined on the branch-defining element or any descendant elements.” The second sentence clearly applies only to the branch-defining element, which implies that the first sentence also only applies to the branch-defining element but it could also be read as “any element in the branch that specifies @keyscope”, ie., “each key scope in the branch”.

If the first sentence instead said “each key scope for the branch” or “each key scope of the branch-defining element” then it would be unambiguous, I think.

We must have discussed this at the time the proposal was approved but I don’t have any memory of it.

So my question is: was it the original design intent that dvrKeyscopePrefix/Suffix apply to *all* key scopes in the filtered branch or only to the branch-defining element?

If the intent was that it only apply to the branch-defining element then I think the language needs to be adjusted to make that clear.

Oxygen 24.1 and OT 3.7.1 both implement the branch-defining-element-only behavior, which suggests that that was the intent.

If the intent was that every explicitly-specified keyscope gets the prefix or suffix then I think we need to make that clearer and/or discuss whether that’s actually the correct behavior and consider changing it for DITA 2.0.

Consider this case:

<dvrKeyscopePrefix>scope-one</dvrKeyscopePrefix>

</ditavalmeta>

…

</topicgroup>

</topicref>

Here the branch root has no explicit @keyscope and a subordinate topicref specifies @keyscope=”subscope-01”.

Is the effective scope of the topicgroup (A) “scope-one.subscope-01” or (B) “scope-one.scope-onesubscope-01”?

My expectation/desire is option (A): the subscope name is not changed.

But if the answer is (B), and I, as the map author, want the effective keyscope to be “scope-one.subscope-01” then I think that requires that I add a topicgroup with a ditavalref that does nothing but unset the keyscope prefix:

<dvrKeyscopePrefix>scope-one</dvrKeyscopePrefix>

</ditavalmeta>

</ditavalmeta>

</ditavalref>

…

</topicgroup>

</topicref>

That will presumably work but it seems a bit much, especially if there’s no obvious utility in adding a prefix to *all* descendant keyscopes—I cannot think of reason why you’d ever want that and many reasons why you would *not* want that.

Cheers,

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

dita message