Working keyrefs in published submaps: Importing keys into submaps

[jrehahn]

Hi,

I have a question regarding the key/keyref in submaps:
So, our status quo is that we have one "main" map which we build that contains a platform-wide overview of the documentation.
However, in some cases we need to also publish some of the software product documentation (that is within the main map) independently.
Since we implemented keys and keyrefs to the main map, all links to topics that are not part of the published submap are, obviously, broken now. Before, the conrefs of the href were at least still rendering the content, even without the source topic being included in the published (sub) map.

I can imagine, of course, that it is generally best practice to reference all topics that you need in a published map .
But since this seems to me an endless task atm, I was wondering if there is another solution:
1. Can I somehow import the keys from the "mother" (main) map?
2. I also had the idea of using DITAVAL to filter the main map in specific transformation scenarios to build submaps, but this seems to only partly solve the issue: Can a conkeyref in this case render the content correctly?

[xephon]

Hard to give a good answer without knowing your structure exactly. Let's assume you have spaghetti linking and everything links to everything. A link creates a dependency. And if the missing target is gone, you get an error message. If I were you, I would define an authoring rule that links from one submap to the other submap are prohibited in general. And error messages and warnings regarding broken links should not be ignored. They indicate bad style and those issues should be solved.

You can create relationship tables and store them on the main map or in separate maps to connect topics from different submaps. This keeps your topics independently.

[Radu]

Hi,
Maybe keep some separate DITA Maps which define all keys used for links and conrefs and then refer to them in all publication DITA Maps:
https://github.com/oxygenxml/dita-proje ... ster/links
Regards,
Radu

[jrehahn]

Hello,

thanks for the feedback. We will incorporate some linking rules then!

Best regards,
Josie

[chrispitude]

Hi Josie,

We run into a similar situation here. We have a top-level map with many "book" submaps that we publish as WebHelp. We also publish these book submaps individually as PDFs.

In our case, we use keyscoped submaps as described here:

Oxygen XML Blog > Cross-Book Links

You must ensure that the link text for cross-submap links are explicitly provided. We automate this with the peer-map refactoring operation and Schematron quick-fix described here (thanks to Radu for implementing this!):

Oxygen XML Blog > Resolving DITA Cross-References in Refactoring Operations

Here is an Oxygen testcase that you can experiment with (it includes the peer-map refactoring operation and Schematron quick-fix described above):

maps_and_scoped_submaps.zip

Note the following caveats:

• Content reuse between separately published submaps must use @conref instead of @conkeyref (unless you maintain a separate reuse map that defines *all* the keys as discussed earlier in this thread).
• Topic keyrefs into scoped peer maps generate nuisance DOTJ047I "unresolved key" messages. I filed DITA-OT issue #4068 (DOTJ047I (unresolved key reference) should not be issued for references into declared peer maps) for this.