Problem Using conkeyref with glossentry

[Eddie]

Hello,

Using V19.0, if I try to insert a glossentry by conkeyref using the Reuse Content page, I get a "Conref was not expanded" error.
It seems that Oxygen isn't picking up the referenced id in the "Reference to" field - just the key name. When I select a target ID and click "Insert", Oxygen inserts a glossentry with the key name but no /id after it. For example, if the key name is "canon", I get:

Code: Select all

    <glossentry id="id_i4x_cnt_4bb" conkeyref="canon">

        <glossterm/>

    </glossentry>

The same thing happens if I double-click a target ID.
I've tested this inserting a few other elements (but not all) and it doesn't seem to happen.

Am I doing something wrong?

Cheers,
Eddie.

[Radu]

Hi Eddie,

A <glossentry> element is a DITA topic specialization. So it is not a DITA element, but a DITA topic.
According to the DITA specification:

http://docs.oasis-open.org/dita/dita/v1 ... fattribute

For content references from map elements to map elements or topic elements to topic elements, the value of the @conkeyref attribute is a key name, where the key must be bound to a map element (for references from map elements) or a topic element (for references from topic elements).

For all other elements, the value of the @conkeyref attribute is a key name, an optional slash ("/"), and the ID of the target element, where the key name must be bound to the map or topic that contains the topic element.

Because a <glossentry> is actually a topic (specialized from the base DITA <topic> element), the first quote applies to it. So whenever you add a conkeyref on a glossentry, you must not add an element ID after the key name, the key should be enough information to point to the target glossentry.

For example let's say I have a DITA file containing inside a glossentry:

Code: Select all

<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">

<glossentry id="flowers.genus">

    <glossterm>Genus</glossterm>

    <glossdef>A low-level taxonomic rank used in the classification of living and fossil organisms.

        Other well-known taxonomic ranks are domain, kingdom, phylum, class, order, family, and

        species, with <term>genus</term> fitting between family and species. The scientific name of

        a genus may be called the generic name: it is always capitalized.</glossdef>

</glossentry>

and in the DITA Map I define a key for it:

Code: Select all

<topicref href="concepts/glossaryGenus.dita" keys="genus"/>

then I can create another DITA file containing a glossentry which has a conkeyref to the first one:

Code: Select all

<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">

<glossentry id="glossary" conkeyref="genus">

    <glossterm>Glossary</glossterm>

    <glossdef></glossdef>

</glossentry>

But I may not understand your current setup. For example did you add multiple glossentries in the same DITA topic and now you are trying to conkeyref to them from other places?

Regards,
Radu

[Eddie]

Hello Radu.

Thanks for the quick reply. We noticed this because we have someone creating a general manual for some printing software, as well as specific manuals for specific printers (Canon, Ricoh, etc). Each of those manuals has a glossary file (created with multiple glossentries in a glossgroup).

They want to make a glossary for the general manual that pulls some content from the product-specific glossaries using conkeyref at glossentry level.
Is it better to use conref in this case? (It seems to work OK.)

You said "you must not add an element ID after the key name", but I tried doing this in text view and it works fine - no errors and the output is OK.

Cheers,
Eddie

[Radu]

Hi Eddie,

You said "you must not add an element ID after the key name", but I tried doing this in text view and it works fine - no errors and the output is OK.

Actually I said (or wanted to say) something like "you must not add a topic ID after the key name". The glossentry is a topic. You could have used this "keyName/idValue" construct to refer to an ID of an element inside the glossentry, for example to a paragraph located there.
In my opinion I think that according to the DITA specfication in this case the publishing should fail, I added an issue for it maybe the DITA OT developers could give me their opinion on this:

https://github.com/dita-ot/dita-ot/issues/2816

Coming back to how your case could be made to work, if you have a glossgroup looking like this:

Code: Select all

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

            <glossgroup id="glossgroup">

                <title>GlossGroup</title>

                <glossentry id="entry1">

                    <glossterm>Genus</glossterm>

                    <glossdef></glossdef>

                </glossentry>

                <glossentry id="entry2">

                    <glossterm>Genus</glossterm>

                    <glossdef></glossdef>

                </glossentry>

            </glossgroup>

you can define in the DITA Map multiple keys, each pointing to an individual topic (glossentry) in the glossgroup:

Code: Select all

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

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

and make the conkeyrefs point directly to those specific keys.

Regards,
Radu

[Eddie]

Hello Radu,

Thanks again for the reply.

I understand the reasoning behind not allowing ids after the key name now, although the way the file was originally constructed makes sense to me. (It seems cumbersome to define a key for every glossentry.)

A couple of follow-up questions based on this:

Should the topic be passing validation if it is written like this? (glossentry conkeyref="keyname/id")
Shouldn't the behaviour be the same with conref?

Thanks for posting the question to DITA OT on github. I'll keep an eye on it.

Cheers,
Eddie

[Radu]

Hi Eddie,

So:

Should the topic be passing validation if it is written like this? (glossentry conkeyref="keyname/id")

Oxygen's "Validate and check for completeness" action from the DITA Maps Manager should complain about this type of conkeyref. At least it does for me, I'm using Oxygen 19.1.

Shouldn't the behaviour be the same with conref?

No. A key is defined as pointing directly to an individual topic element. So even if you define a key like this:

Code: Select all

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

it is considered as if the key is mapped to the first topic ID found inside the "glossgroup.dita".

Regards,
Radu

[Eddie]

Hello Radu,

About picking up the error when validating glossentry conkeyref="keyname/id", this seems to be an improvement in V19.1.
I installed it yesterday evening and validating at map level does pick it up. (But validating the individual topic does not.) Until then, I'm sure Oxygen wasn't picking up the error. I installed over V19.0, so I can't go back and check, but I do still have V18.1 installed and this allows the file to pass validation at both map and individual topic level.
(Not a criticism, by the way, just a partial explanation of why we were confused.)

Appreciate the help as always.

Eddie.

[Radu]

Hi Eddie,

Yes, it's possible we fixed a bug sometime between Oxygen 18.1 and 19.1.
About topic-level validation, this kind of validation only checks the current file. It never goes and parses the conkeyreffed file to see if that referenced ID is the ID of an element or of a topic. We do that for performance reasons, as there might be lots of conrefs/conkeyrefs, hrefs or keyrefs in the topic and automatic validation is done very often, every time you type, possibly on topics which also may not reside on the local disk drive.
So if you want full validation you should always go with the "Validate and check for completeness".

Regards,
Radu

[Eddie]

Hello Radu,

Apologies for bringing this up again.
I tried creating a glossary the way you suggested (multiple keys, each pointing to an individual topic (glossentry) in the glossgroup) and, as far as I can tell, it's not allowed. The reason being, the key points to the glossgroup, but you have to specify the glossentry id if you want to pull any glossentry besides the first one in the group.
The only ways I can see of reusing glossentries with conkeyref are as follows:
1. Create each glossEntry as an individual glossEntry topic. Define a key for each glossEntry.
2. Create each glossEntry as an individual glossGroup topic (only one entry per group). Define a key for each glossGroup.

Either way, it seems unnecessarily bulky.

Cheers,
Eddie.

[Radu]

Hi Eddie,

In one of the examples I gave you above, you had a glossgroup containing gloss entries, one of the glossentries had id="entry1" and in the DITA Map there was a keydef like this:

Code: Select all

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

Did you try that approach?

Regards,
Radu

[Eddie]

Hello Radu,

Yes, I tried what you suggested. For example, the main glossary reuses some entries from the Canon glossary, so I have these keys in the map:

Code: Select all

        <keydef keys="canon-1" href="canon-gloss.dita#canon-gloss-1"/>

        <keydef keys="canon-2" href="canon-gloss.dita#canon-gloss-2"/>

        <keydef keys="canon-3" href="canon-gloss.dita#canon-gloss-3"/>

        <keydef keys="canon-4" href="canon-gloss.dita#canon-gloss-4"/>

And glossentries in canon-gloss.dita with IDs "canon-gloss-1" etc.

If I try to insert any of those entries in the main glossary using conkeyref, I get the same error:

Key reference to topic must not contain topic ID "canon-gloss-1".

Which, although inconvenient, makes sense according to what you explained earlier.

Cheers,
Eddie.

[Radu]

Hi Eddie,

I tested a similar situation on my side, with the conkeyref looking like this:

Code: Select all

<glossentry id="ddl" conkeyref="canon-1">

        <glossterm></glossterm>

        <glossdef></glossdef>

    </glossentry>

In my opinion the "Validate and check for completeness" should not report an error in this case because it's a valid situation so I added an internal issue to report an error in this case.
But the publishing works so you should continue with this approach.

Regards,
Radu

[Radu]

Hi,

We just released Oxygen XML Editor 20 which no longer reports an error in this case listed above:

Code: Select all

<glossentry id="ddl" conkeyref="canon-1">

        <glossterm></glossterm>

        <glossdef></glossdef>

    </glossentry>

Regards,
Radu