Sharing Content Between Two Doc Sets

[cjboorman]

Hi,

I'm trying to figure-out how to share content between two doc sets, while keeping their source files in separate folders—and I haven't had much success.

I started by creating one ditamap with about a hundred *.dita files in the same directory. Today, I started on a second document, and I want to keep the ditamap and *.dita source files in a separate directory. Both of these directories are subdirectories inside my project directory (beside one another).

I can generate the doc for both doc sets at once—using a ditamap that includes the two other ditamaps; but what I would like to do is generate each doc set separately. When I do that though, I get broken URLs—to topics that are not in the same folder as the doc set's ditamap. What is it that I'm not doing (that I should be doing)?


Thanks,

Chris.

[alin]

Hi Chris,

Referencing to a DITA topic, map or to a binary resource (for example: image) that is located outside of the folder where the main DITA map is located usually leads to problems when publishing the content using the DITA Open Toolkit. The DITA OT does not handle it well when links to topics that are outside the directory where the published DITA map is found. By default it does not even copy the referenced topics to the output directory.

For each of your two maps, create another DITA map that is located in a folder path above all referenced folders and reference from it the original DITA map. Then transform this DITA map instead.

Regards,
Alin

[cjboorman]

As you suggested, I do have a "parent" ditamap above my two document's ditamaps - but the only problem with that is that I cannot generate one doc set at a time; I have to generate both doc sets, which takes several minutes.

Are you telling me that if I want to generate each doc set separately, I'll have to have all of the dita topics from both of my doc sets in the same folder? Gee, that would mean I'll have over a thousand topics in one folder when I finished writing nineteen doc sets. Ouch!

Would Master Documents help with this problem?

[alin]

Hello,

There are two possible solutions:

1. First scenario:

   As you suggested, I do have a "parent" ditamap above my two document's ditamaps - but the only problem with that is that I cannot generate one doc set at a time;

   You should have two "parent" ditamaps, not one. Each of your original ditamaps should be referenced from a parent ditamap that is above all referenced topics in your folder structure on disk. This way you can publish each parent map independently.
   
2. Second scenario:

   Are you telling me that if I want to generate each doc set separately, I'll have to have all of the dita topics from both of my doc sets in the same folder?

   No, you can keep the topics in separate folders. You should move the ditamaps outside the topics folders. Thus the ditamaps can safely reference topics in any folder that is on the same level or below them.
   This solution has the advantage that you will not need additional "parent" maps.
   
   Note: Moving the ditamaps will also require updating the topicrefs to reflect the new location. You can use the Refactoring -> Move resource contextual action from the DITA Maps Manager view. This action will move your map and will also automatically update the topic references.
   You can read more about this action in our User Manual: https://www.oxygenxml.com/doc/versions/ ... ource.html

Would Master Documents help with this problem?

The Master Files support will not help in this case, because the DITA-OT publishing engine is not aware of the Master Files that you set in oXygen.

Regards,
Alin

[cjboorman]

Thanks. I found it quite confusing, that the UI suggests that using master documents is an option for my usage scenario - when it's not. You should add a note to your documentation that lets the user know that the master document feature does not apply to DITA-OT docs (it currently doesn't say so anywhere).

[alin]

The benefits of using Master Files are listed here: https://www.oxygenxml.com/doc/versions/ ... efits.html.

The Master Files Support is used by Oxygen XML Editor to determine the context for operations such as validation, content completion, refactoring, or search for XML, XSD, XSL, WSDL, and RNG modules.
It has no effect when you publish DITA content to HTML or any other output format.
Also in case of XML documents, this support is limited to modules referenced using the XInclude or external entities mechanism.

[cjboorman]

It has no effect when you publish DITA content to HTML or any other output format.

• This feature appears in the UI when working with DITA content.
• Your documentation doesn't specifically state that this feature does not apply to DITA authors.

This is unnecessarily confusing for DITA authors. I suggest you either document it, or remove it from your UI.


Just trying to help. Thanks.