keydef: why plural keys and keywords?

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

keydef: why plural keys and keywords?

Post by RBVanDyke » Sat Apr 11, 2020 3:12 am

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:

Code: Select all

  <keydef keys="summer rain">
    <topicmeta>
      <keywords>
        <keyword>summer</keyword>
        <keyword>rain</keyword>
      </keywords>
    </topicmeta>
  </keydef>
That structure validates without error.

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

Code: Select all

<p>It's <ph keyref="summer"/> so we expect it to <ph keyref="rain" />.</p>
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

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

Re: keydef: why plural keys and keywords?

Post by RBVanDyke » Sat Apr 11, 2020 3:19 am

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...

Radu
Posts: 7029
Joined: Fri Jul 09, 2004 5:18 pm

Re: keydef: why plural keys and keywords?

Post by Radu » Mon Apr 13, 2020 7:10 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

Re: keydef: why plural keys and keywords?

Post by RBVanDyke » Mon Apr 13, 2020 8:30 pm

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:

Code: Select all

<topicmeta>
      <keywords>
        <keyword keys="summer hot-weather">summer</keyword>
        <keyword keys="rain sprinkle pour deluge">rain</keyword>
      </keywords>
    </topicmeta>
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

Radu
Posts: 7029
Joined: Fri Jul 09, 2004 5:18 pm

Re: keydef: why plural keys and keywords?

Post by Radu » Tue Apr 14, 2020 8:53 am

Hi Riley,

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

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

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

Re: keydef: why plural keys and keywords?

Post by RBVanDyke » Mon Apr 20, 2020 11:16 pm

The Write The Docs correspondent who contributed the first example updated his reply to this:

Code: Select all

<keydef keys="deluge rain pour sprinkle">
 <topicmeta>
  <keywords>
   <keyword>rain</keyword>
  </keywords>
 </topicmeta>
</keydef>
 <keydef keys="summer hot-weather">
  <topicmeta>
   <keywords>
    <keyword>summer</keyword>
   </keywords>
  </topicmeta>
 </keydef>
This is on my short list of things to validate / explore.

Cheers & thanks to all,
Riley
SFO

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

Re: keydef: why plural keys and keywords?

Post by RBVanDyke » Tue Apr 21, 2020 1:34 am

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...

Radu
Posts: 7029
Joined: Fri Jul 09, 2004 5:18 pm

Re: keydef: why plural keys and keywords?

Post by Radu » Tue Apr 21, 2020 7:21 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

RBVanDyke
Posts: 83
Joined: Wed Feb 11, 2015 11:25 pm
Location: San Francisco, California USA
Contact:

Re: keydef: why plural keys and keywords?

Post by RBVanDyke » Fri Apr 24, 2020 8:56 pm

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

Post Reply