Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Having trouble installing Oxygen? Got a bug to report? Post it all here.
Anonymous1

Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Anonymous1 »

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
Costin
Posts: 829
Joined: Mon Dec 05, 2011 6:04 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Costin »

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
Costin Sandoi
oXygen XML Editor and Author Support
Anonymous1

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Anonymous1 »

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?
Costin
Posts: 829
Joined: Mon Dec 05, 2011 6:04 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Costin »

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?
Costin Sandoi
oXygen XML Editor and Author Support
Anonymous1

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Anonymous1 »

I just checked it and it does not make a difference.
Costin
Posts: 829
Joined: Mon Dec 05, 2011 6:04 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Costin »

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
Costin Sandoi
oXygen XML Editor and Author Support
Anonymous1

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Anonymous1 »

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.
ionela
Posts: 402
Joined: Mon Dec 05, 2011 6:08 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by ionela »

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
Ionela Istodor
oXygen XML Editor and Author Support
ckabstein
Posts: 142
Joined: Fri Apr 24, 2015 12:28 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by ckabstein »

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
oXygen XML Editor 25.0 build 2023013006
DITA OT 3.7.3
Radu
Posts: 9046
Joined: Fri Jul 09, 2004 5:18 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by Radu »

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
ckabstein
Posts: 142
Joined: Fri Apr 24, 2015 12:28 pm

Re: Keywords not visible in output (PDF/WebHelp) when using sub-ditamaps

Post by ckabstein »

Hi Radu,

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

Best,
Christina
oXygen XML Editor 25.0 build 2023013006
DITA OT 3.7.3
Post Reply