Key references not showing up in PDF

[Carl]

Hi. I'm new to OxygenXML and to Dita. I'm taking over a doc set from a previous writer. He made liberal use of key references to reference topics. This has caused problems in our PDF output for some reason. What I've seen so far:

• The referenced topic simply disappears, leaving a blank space that our reviewers flag as missing text (example: "Users can monitor data from the .")
  The referenced topic is listed, but with no hyperlinking (example: "Users can monitor data from the Monitoring page.")
  The referenced topic is listed, with a hyperlinked page reference (example: "Users can monitor data from the Monitoring page on page 30.")

I can't figure out why and when Oxygen will include or omit the reference. I've verified that the code is sound: it appears in the reusable components list, and the key references have been added to the topics. (I haven't checked every single reference though, but they look correct in my spot checks).

I believe the PDF transformation is the stock one that comes with Oxygen.

My workaround thus far has been to replace these key references with normal cross references. These always come out properly in the PDF. But what are the pros and cons of using direct cross references vs indirect key references?

Any ideas on how to troubleshoot?

[Radu]

Hi Carl,

What version of Oxygen are you using? Does the publishing process show any errors in the Errors list when finished?
If you edit the transformation scenario, in the Parameters list there is a parameter called "fix.external.refs...", could you try to set it to "yes" and try again?

https://www.oxygenxml.com/doc/versions/ ... -refs.html

Regards,
Radu

[Carl]

Hi Radu.

I am using OxygenXML Author 20.1, build 2018080903.

I checked the settings for the PDF transformation and it already shows "true" for fix.external.refs.com.oxygenxml

There were a number of errors and warnings after the transformation, but none that obviously relate to referenced material. I saved the error log to an html file, but I don't see a way to attach a file to a reply here?

Finally, I have seen a fourth variation of the results:

• The referenced topic is hyperlinked, while the accompanying page reference is not (example: "Users can monitor data from the Monitoring page on page 30").

This is the opposite of the third option in my original message.

Again, I have scrutinized the key references in all these instances and they are all invoked in the same way.

[Radu]

Hi Carl,

I need more details to help further. Ideally I would have some kind of sample DITA Project to test on my side.
In the Oxygen Preferences->"DITA / Logging" page you can switch the "Show Console Output->Always", then run the transformation. Besides the "Errors" list there will be also a "DITA OT" console view containing all the console output received from the DITA OT processor. Maybe you can save that output to a file and send it via email to "support@oxygenxml.com". One more thing, if you open the main DITA Map in the DITA Maps Manager view, there is a "Validate and check for completeness" action on the toolbar there, does it report any error? If so, you may want to correct those validation problems first.

Regards,
Radu

[Carl]

Hi Radu. The key references problem went away once I fixed all the validation and transformation issues.

Thanks for steering me in the right direction.