Oxygen XML Forum

Hello,

I'm not sure whether this is a bug or if my expectations of the "Root map" option in the DITA Maps Manager are wrong.

Situation
We have a main ditamap that references many sub-ditamaps. Only the main ditamap references the keyword ditamap. If I create an output (PDF or WebHelp) from the main ditamap, all keywords show up as intended.

Problem
If I create an output (PDF or WebHelp) from a sub-ditamap, the keywords do not show up in the output. The error message confirms this: "Unable to find key definition for key reference in root scope". This result is expected because they sub-ditamap does not know the location of the keyword definitions.

However, in the DITA Maps Manager I've set the "Root map" option to be the main ditamap. Is this option not used when creating output but only for displaying the keywords in Oxygen? Would the best practice be to reference the keyword ditamap in every sub-ditamap?


We are using Oxygen 19, DITA OT 2.4.4 and a custom framework.

Thank you,
Benjamin

Hello,

First thing you should try is validate the DITA Map you are trying to publish (if I correctly understood this is actually one of the submaps).
So, you should apply the Validate and Check for Completeness action on the DITA Map you are transforming and if the validation reports errors, please try to fix them first.

Another possible cause could be the one described HERE. So, if you have submaps, or other resources that are outside the folder of the main DITA Map, you should either make sure to bring all resources together in the same folder hierarchy, or try using the "fix.external.refs.com.oxygenxml" parameter in the transformation scenario configuration (applicable only if you run the transformation from the oXygen GUI).

Regards,
Costin

Thanks for your answer Costin.

The validation check of the sub-ditamap reports that the key definitions cannot be found. This is as expected, since there are no keyword ditamaps referenced in the sub-ditamap.

But I would have hoped that the "Root map" setting would also be taken into account when generating a PDF or WebHelp output. But it looks like this option is only applied for topics that are open in Oxygen and contain keywords and not for the output generation.

Is not the case. Is this a bug or intended behavior?

Sorry, I now noticed that in my previous post I omitted to include the link for my 2nd advice:

Another possible cause could be the one described HERE. So, if you have submaps, or other resources that are outside the folder of the main DITA Map, you should either make sure to bring all resources together in the same folder hierarchy, or try using the "fix.external.refs.com.oxygenxml" parameter in the transformation scenario configuration (applicable only if you run the transformation from the oXygen GUI).

Could you please try the suggestions as per the User-Guide page and see if this makes any difference?

I just checked it and it does not make a difference.

Hi B-E-N,

I double checked this behavior with my team and it seems that indeed, setting the "Root map" option to be the main ditamap. Is only used for displaying the keywords in Oxygen, without having any influence over the generated output.

Regards,
Costin

Thank you for clarifying this.

Can you imagine changing this behavior in a future Oxygen version?

The workaround of course would be to reference the keyword ditamaps in each sub-ditamap. But having only to maintain the keyword ditamap reference in the main ditamap of each project is a bit more convenient.

Hello,

I have logged this as an improvement request to our issue tracking tool. This will be analyzed and it found appropriate it will be implemented in a future version of oXygen XML (long term).

Regards,
Ionela

Hi all,

Regarding this hopefully soon implemented feature I would like to add that it would be extremely useful if the "Validate and Check for Completeness" dialog contained an option that allows you to determine from which ditamap the keys are gathered - in this case the root map.
Use case: Sometimes, an author may just want to validate a submap and not the whole document starting from the main map.

Thanks,
Christina

Hi Christina,

We plan to release Oxygen 21 at the beginning of February 2019. One aspect related to the "Validate and Check for Completeness" that will be changed in Oxygen 21 is the fact that the keys will always be gathered from the DITA Map specified in the root DITA Map combo box.
So you will be able to properly validate a submap which has key references as long as the keys are properly defined in the main root map.

Regards,
Radu

Hi Radu,

That's great news! Thanks for letting us know.

Best,
Christina