Show Variables Overridden From Higher-Level Keyscopes

[chrispitude]

In the OASIS DITA 1.3 specification, a variable definition in a parent keyscope always overrides a definition in a lower-level keyscope.

Consider the following scenario, where I have three books and I want to define "Product" differently in each book via keyscope, but I forget to apply a keyscope to book C:

image.png (56.16 KiB) Viewed 725 times

Because bookC.ditamap is accidentally in the top-level keyscope, the "Product C" definition wins and is pushed into Book A and Book B too. But the DITA Maps Manager shows the local (not used!) definitions in Book A and Book B, resulting in writer confusion.

Keyscope behaviors are confusing, especially for nontechnical users. To help writers understand what is happening, the DITA Maps Manager could apply strikethrough to lower-level variable definitions that are overridden by a higher-level definition (red is used only to show additions):

image.png (72.68 KiB) Viewed 725 times

In addition, the existing tooltip could be extended to indicate where the overriding definition comes from.

This enhancement would be useful both to verify expected overriding behaviors, and to catch/debug unexpected overriding behaviors.

A testcase is included:

oxygen_show_overridden_variables.zip

(4.29 KiB) Downloaded 124 times

Also, note that in the DITA Maps Manager, the bookA.ditamap title shows the overridden value ("Book for ProductC"), but the topicA.dita title does not ("My Topic for ProductA"). This is an inconsistency with the published output that adds further confusion to debugging. A separate bug issue should probably be filed for this.

Although this scenario is simple, we encountered this issue in a WebHelp map that included included 50+ books, each included via submap with keyscopes, grouped into topicgroups, with some top-level support topics that also define their own keys. Our book keys were being overridden from a submap that was accidentally not keyscoped, but it was difficult for us to debug the source of the issue.

[Radu]

Hi Chris,

Looking at your sample with the Oxygen 25 (beta) application started and things look better:

Screen Shot 2022-07-25 at 12.01.02.png (170.99 KiB) Viewed 703 times

You still have those actual key definitions like "Product=Product A", "Product=Product B", "Product=Product C" but they are correct in my opinion as they are the actual key definitions.

Regards,
Radu

[chrispitude]

Hi Radu,

I'm glad to see that the topic titles now show the correct overridden variable value, thank you!

Regarding the other aspect, I completely agree that the overridden variable definitions should show their original values, as they currently do. The idea was to add some kind of visual indicator (strikethrough, or fading the color a bit, or some kind of tiny icon) that indicates that the definition has been overriden and is never used.

When these overrides occur, it is difficult to know that they happened. Even Validate and Check for Completeness does not report these overrides.

Actually, thinking along those lines... Validate and Check for Completeness is probably a better way to catch overrides than a visual override indicator. A new "override" category could be added:

image.png (46.61 KiB) Viewed 697 times

Or, the existing Report duplicate key definitions check could also report overrides (with a different message).

[Radu]

Hi Chris,

I added an internal issue to consider reporting such cases for validate and check for completness:

EXM-50982 Report key definitions with same name in different key scopes

Regards,
Radu