Topics

keys and scoped keys #conref

Wim Hooghwinkel
 

Hi all,

I’m trying to figure out a use case for scoped keys. After reading this very helpfull article (https://www.oasis-open.org/committees/download.php/56472/Understanding%20Scoped%20Keys%20In%20DITA%201.3.pdf) I’m wondering if anything has changed for OT 3.x. I’m now using OT 2.5.x.

This is how I would have expecetd it to be implemented - and what I actually need:

In my main project (ditamap) I have defined several keys. Let’s say Key1 defines 'Blue' and Key2 defines ’Square'. 
So all te topics and submaps in my project will resolve keyref to Key1 as 'Blue' and keyref to Key2 as 'Square'.
Now, in one of my submaps I need to refer to a Red Square. I set the keyscope of that map to 'mymapscope'. I define a key named 'Key1’ with value 'Red'. And expect the topics in that map to resolve keyref to Key1 to 'Red', so they display 'Red  Square'. 
But, unfortunately, that’s not the case. The still show 'Blue Square'.

From the above article, I learned that even with key scopes, the parent definition wins over a nested one. For my use case, that would implie that I have to remove the keydefs from my main map, set a keyscope for each and every submap, use the same definitions everywhere, except for one, just to be able to make use of the keyscope features. That adds a lot of overhead and managing keydefs.

So, am I right to conclude that a nested keydef, even within it’s own keyscope, does NOT override a parent keydef? Did this change in OT 3.x - or can anyone point me to an elegant solution for this without the need to repeat the same keydefs for every parrallel nested map or topic?

thanks!


Vriendelijke groet / Kind regards,
 
Wim Hooghwinkel






ekimber@contrext.com
 

If you have:

 

+ keys=”key1” {blue}

++ keyscope=”scope1”

+++ keys=”key1” {red}

 

Then the resolved value of a reference to key “key1” will be “blue” in all contexts because the highest declaration wins.

 

That is keys are not like normal variables in programming languages, where the nearest declaration wins. This is so that the owner of the root map always has ultimate control over the definitions of all keys.

 

However, with the above you can refer to key “scope1.key1” which will resolve to the value “red”. But that’s probably not useful for your case.

 

So as you determined, if you have two peer scopes and you want the same key name to resolve to different values in those two scopes then the keys need to be defined in the scopes, not in an ancestor scope.

 

Normally you would do this by having a separate map that defines the keys and then include that map into both scopes. This is consistent with the general practice of putting key definitions into submaps to make them easier to manage.

 

So you could have something like:

 

+ root map

++ keyscope=”scope1”

+++ keys=”key1” {red}

+++ Reference to keydef map “colors.ditamap”

++ keyscope=”scope2”

+++ Reference to keydef map “colors.ditamap”

 

Where colors.ditamap is:

 

+ keys=”key1” {blue}

+ keys=”key2” {red}

 

With this structure, “key1” resolves to “red” in the context of scope1 and “blue” in the context of scope2. The definition of key “key1” in scope1 overrides the definition of key1 in colors.ditamap because it comes before the reference to colors.ditamap.

 

Cheers,

 

E.

--

Eliot Kimber

http://contrext.com

 

 

 

From: DITA Users on behalf of DITA Users
Reply-To: DITA Users
Date: Wednesday, September 5, 2018 at 8:36 AM
To: DITA Users
Subject: [dita-users] keys and scoped keys

 

 

Hi all,

 

I’m trying to figure out a use case for scoped keys. After reading this very helpfull article (https://www.oasis-open.org/committees/download.php/56472/Understanding%20Scoped%20Keys%20In%20DITA%201.3.pdf) I’m wondering if anything has changed for OT 3.x. I’m now using OT 2.5.x.

 

This is how I would have expecetd it to be implemented - and what I actually need:

 

In my main project (ditamap) I have defined several keys. Let’s say Key1 defines 'Blue' and Key2 defines ’Square'. 

So all te topics and submaps in my project will resolve keyref to Key1 as 'Blue' and keyref to Key2 as 'Square'.

Now, in one of my submaps I need to refer to a Red Square. I set the keyscope of that map to 'mymapscope'. I define a key named 'Key1’ with value 'Red'. And expect the topics in that map to resolve keyref to Key1 to 'Red', so they display 'Red  Square'. 

But, unfortunately, that’s not the case. The still show 'Blue Square'.

 

From the above article, I learned that even with key scopes, the parent definition wins over a nested one. For my use case, that would implie that I have to remove the keydefs from my main map, set a keyscope for each and every submap, use the same definitions everywhere, except for one, just to be able to make use of the keyscope features. That adds a lot of overhead and managing keydefs.

 

So, am I right to conclude that a nested keydef, even within it’s own keyscope, does NOT override a parent keydef? Did this change in OT 3.x - or can anyone point me to an elegant solution for this without the need to repeat the same keydefs for every parrallel nested map or topic?

 

thanks!



Vriendelijke groet / Kind regards,
 
Wim Hooghwinkel

 

 

 

Matt Lorenzi
 

I am going to add to this thread rather than start a new one. I am looking to use a keyspace or map to house reusable content such as product names, document numbers, etc. I learned that before keyscope you would need a unique keyname for each keyword entry. But with the introduction to keyscope you can reuse the keyword, but further differentiate it using keyscope. Do I have this right? 

Given all of that, is this correct markup for use of keyscope? This is a dummy example of my keyspace:

<map id="keydefs">

    <!-- product name -->

    <title>Key Definitions</title>

    <keydef keys="inverter" keyscope="1000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 1000</keyword>

            </keywords>

        </topicmeta>

    </keydef>

    <keydef keys="inverter" keyscope="2000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 2000</keyword>

            </keywords>

        </topicmeta>

    </keydef>    

    <keydef keys="inverter" keyscope="3000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 3000</keyword>

            </keywords>

        </topicmeta>

    </keydef>

 

</map>

Radu Coravu
 

Hi Matt,

After you define these keys in different key scopes you can explicitly refer to any of them like:

<ph keyref="3000.inverter"/>
Or as other use cases you can refer to the same DITA topics in various key scopes and have them published with different content in each key scope:

https://oxygenxmlblog.netlify.com/presentation-reuse/reuse_keyscopes.html

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 2/7/2020 1:35 AM, Matt Lorenzi via Groups.Io wrote:
I am going to add to this thread rather than start a new one. I am looking to use a keyspace or map to house reusable content such as product names, document numbers, etc. I learned that before keyscope you would need a unique keyname for each keyword entry. But with the introduction to keyscope you can reuse the keyword, but further differentiate it using keyscope. Do I have this right?
Given all of that, is this correct markup for use of keyscope? This is a dummy example of my keyspace:
<map id="keydefs">
    <!-- product name -->
    <title>Key Definitions</title>
    <keydef keys="inverter" keyscope="1000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 1000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
    <keydef keys="inverter" keyscope="2000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 2000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
    <keydef keys="inverter" keyscope="3000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 3000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
</map>