Oxygen XML Forum

oXygen XML Editor V22

As a DITA newbie, I'm confused by keydef's use of the plurals keys and keywords. It seems to me the use of plurals is trying to tell me something. But I can't make use of more than one key to produce a single replacement.

I can create the following keydef that contains two keys values and two keyword definitions:
That structure validates without error.

But IF I try to make use of the rain key to replace a second phrase (ph) as follows:
THEN I end up with:

It's summer so we expect it to summer.

I've tried using Web resources and the oXygen XML v22 online help to research this on my own. But all those resources repeat the same single keys and single keyword example. (Which may also be trying to tell me something...)

So I'm trying to understand why I can create more than one keys value and more than one keyword definition, but can't make use of the second values in a single keydef structure.

Thanks in advance for any insights,
Riley
SFO

I'll add that I've created two separate keydef structures, one for summer, one for rain. No problem. But as I said in my initial post, the use of the plurals keys and keywords seems to have some "secret" meaning I've been unable to decode...

Hi Riley,

Indeed in DITA the @keys attribute can take a space separated list of keys. This means that all those keys point to the same definition, so they can be used interchangeably one instead of the other. So with your first example, using a "keyref" to summer is the same as using a keyref to "rain".
If you use a keyref to a key definition with multiple keywords, the value for that keyref is computed like this:

https://www.oxygenxml.com/dita/1.3/spec ... -text.html

For elements that do not allow the @href attribute, content is taken from the first <keyword> element inside of <keywords> inside of the <topicmeta>.

so in the case of ph with keyref, only the first keyword will ever be used.
So why can multiple keywords be defined? They may be used by the publishing engine if for example they are defined on a topicref to a topic and a list of keywords could be used for search indexing. But on a keydef which does not refer to any particular topic those multiple keywords are not used for anything (at least in the default publishing).

Regards,
Radu

Thanks as always Radu.

Over on the Slack Write the Docs DITA channel, I was offered this possible approach:

Both of your keys are resolving to the first keyword in your example. Try this instead:

I haven't had a chance to test this. But after I do I'll circle back and update this thread. My thought being that someone else may have the same question...

Cheers & thanks 'gain,
Riley
SFO

Hi Riley,

The @keys attribute is not allowed to appear on the "keyword" element so the workaround will not work.

Regards,
Radu

The Write The Docs correspondent who contributed the first example updated his reply to this:
This is on my short list of things to validate / explore.

Cheers & thanks to all,
Riley
SFO

I tried the latest variant, couldn't get it to work. So rather than go further down this rathole I'm setting it aside for the foreseeable future. There are many other more productive DITA learning activities I can pursue...

HI Riley,

You did not mention how the keyrefs looked like and what you expected them to expand to.
So with this last approach these key references:

<ph keyref="deluge"/>, <ph keyref="rain"/>, <ph keyref="pour"/> and <ph keyref="sprinkle"/>

would have all resolved to the word "rain", Similar for the other two key references, they would have resolved to the word "summer".

Regards,
Radu

Thanks as always, Radu.

What this newcomer was thinking, obviously incorrectly, was that keydefs and keywords could be "paired" so that, say, summer could be paired with hot. The element that referenced the keywords could then be formed so as to replace paired elements. Stated another way, a sort of packaging of related replacement values...

Obviously this isn't how it's meant to work. And as I said, I have other DITA learning exercises that will be a more productive application of my time and energy. At least for the foreseeable future...

Cheers & thanks 'gain,
Rileyi
SFO