Linking term to glossary item in glossgroup

[Miriam2]

I am publishing content with a glossary for the first time. My writers have chosen to use glossgroup because they believe it is easier for them to maintain. I need each <term> to link directly to the appropriate item in the output Glossary. The steps I have done to try and achieve this are:

1. Add the glossgroup file to my .ditamap with a topicref and key: <topicref href="glossary.dita" keys="glossary"/>.
2. Add an id to the relevant glossterm (because glossentry is handled as a topic element and so I can't use its ID in my term's keyref).
3. Add a keyref to my term in the form <term keyref="glossary/<glosstermID>">
4. Run Validate and Check for Completeness on my .ditamap.
5. Output with WebHelp Responsive and WebHelp Classic.

Although oXygen validates my link construction, the actual link in both forms of WebHelp breaks. The link is built with the syntax glossary.html#glossary__<termID> but the actual anchor point in the Glossary is built with the syntax glossary.html#<glossentryID>__<termID>.

Is this an error in WebHelp's handling of the link or is this an error in my DITA syntax?

(In addition to being new with glossaries, I am also new with keys/keyref.)

[bogdan]

Hi Miriam,

You can find a more detailed discussion about this subject in another thread on our forum.

In short, this is a known issue already reported to DITA-OT. The validation process should fail (actually this has already been fixed in the current Oxygen development branch and will be available in the next version of Oxygen) and should be reported as an error. This is because, according to the DITA specification, you cannot use keyrefs to indirectly reference glossentries inside a glossgroup.

As an alternative you could define a key for each glossentry in your glossgroup:

Code: Select all

<keydef keys="keyToGLEntry1" href="topics/glossgroup.dita#entry1"/>

<keydef keys="keyToGLEntry2" href="topics/glossgroup.dita#entry2"/>

Then use keyrefs which point directly to those specific keys:

Code: Select all

<term keyref="keyToGLEntry1"/>

Best Regards,
Bogdan Goreci
Oxygen XML Editor

[Miriam2]

Hi Bogdan,

Let me make sure I understand correctly... you're saying that I can't use keyrefs to indirectly reference any element of a glossentry within a glossgroup? I know that I can't use the keyref to reference the glossentry, which is why I was referencing the glossterm instead.

Miriam

[Radu]

Hi Miriam,

Let's try an example. Let's say you have a glossgroup looking like this:

Code: Select all

<!DOCTYPE glossgroup PUBLIC "-//OASIS//DTD DITA Glossary Group//EN" "glossgroup.dtd">

<glossgroup id="glossGroupID">

    <title>GG</title>

    <glossentry id="glentryID">

        <glossterm id="gt1">T1</glossterm>

        <glossdef>D1</glossdef>

    </glossentry>

</glossgroup>

In this particular glossgroup you have two DITA "topics", the "glossgroup" is a DITA topic (because it is a DITA topic specialization) and the "glossentry" is also a DITA topic (because it is also a DITA topic specialization). The glossterm ID "gt1" is defined inside the "glossentry" topic type.

Then in the DITA Map you add a keydef like this:

Code: Select all

  <keydef href="gg.dita" keys="ggKey"/>

Then I have a keyref like this <ph keyref="ggKey/gt1"/>

The DITA 1.3 specs says something like:

For elements that can refer to elements within maps or topics, the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element, where the key name must be bound to either the map or topic that contains the target element.

So that "ggKey" by itself points to the first topic in the glossgroup (which is the glossgroup itself). Then that /gt1 should point to a DITA element which is a direct child of the "glossgroup" topic. But the DITA element with ID gt1 is actually a child of the inner topic "glentryID".

So to make this keyref work you would need to define the key pointing directly to the glossentry ID like:

Code: Select all

  <keydef href="gg.dita#glentryID" keys="ggKey"/>

Regards,
Radu