Cross-deliverable linking

[antonyterrence]

I was trying to follow the instructions on the following page:
https://www.oxygenxml.com/dita/1.3/spec ... liverables.
When I set the glossary.ditamap reference scope to peer, the keys from the glossary topics are not available to the map A. Is that the expected behavior?
There is a Github issue on this. Just wanted to double-check.
https://github.com/dita-ot/dita-ot/issues/1098

[chrispitude]

Hi antony,

When you have an <xref> into a peer map, Oxygen will show the target text in the <xref> in the editor, but the transformation will not be able to compute the <xref> target text. As a result, you will need to manually add the needed text into the <xref> reference into the peer map.

In this forum discussion thread:

Ability to Quickly Insert Previewed Link Text in DITA Topic

there is an enhancement request EXM-50510 for Oxygen to provide assistance adding the text it knows how to resolve into the <xref>, and there is an enhancement request EXM-50518 for Oxygen to help catch <xref> references into peer maps that would be empty in transformation.

Also, this blog post might be interesting to you:

Oxygen Blog - Cross-Book Links

[antonyterrence]

Thank you, Chris. I downloaded the example maps from this project: https://github.com/chrispy-snps/DITA-fi ... html-links
The cross-deliverable linking does not work without running the utility. Is the utility a workaround?

[chrispitude]

Yes, that's correct. DITA peer scopes provide a way to author cross-book links and represent them in the DITA source, but the DITA-OT does not provide transformation support to publish them (because there are too many situation-specific details about how files might be structured, etc.). The script attempts to figure out and resolve the links in the content's final place.

(But remember, if you combine all these maps into a higher-level WebHelp map as described here, then all the cross-references become local instead of cross-book and they will work automatically!)

Note that we do not use the fix_html_xbook_links.pl script in production (yet?):

• For PDFs, we do not implement cross-book links (but maybe some day).
• For online help, we are moving to WebHelp and we will publish everything at once.

There is a possibility that we might use cross-book links between our WebHelp collections some day. If we do that, then we will have to use the script to fix the links between collections.

[antonyterrence]

Thank you. The attribute processing-role=resource-only does not work as expected (it does not cascade down to child topics).
And there is no support for cross-bundle links in DITA OT. Just a little complex scenario if we publish each ditamap separately to a Knowledge Portal (Zoomin). We publish Glossary as a separate publication. And each of our deliverables has glossary referenced as resource-only for the purpose for keyrefs.
When we publish each ditamap, glossary topics are also published local to each output. At then end, we have a standalone glossary in the portal, and glossary topics in each output folder specific to all other deliverables - resulting in many duplicate glossary topics.

[chrispitude]

This situation exactly highlights the inherent difficulty of the DITA-OT trying to support cross-book links in publishing!

I don't have any experience with how Zoomin consumes the content that it publishes. But the only thing the fix_html_xbook_links.pl script does is to fix the HTML links between different publication directories. If Zoomin can incrementally consume one HTML directory out of a set of directories that reference each other, then you should be able to publish a single publication to HTML (help set or glossary), fix the links between the HTML publication directories with fix_html_xbook_links.pl, then upload just the updated publication directory to Zoomin.