Control "Current DITA Map Hierarchy" traverses into warehouse/peer maps

[chrispitude]

Our books have cross-book (peer) and warehouse maprefs to other books:

• Peer books (processing-role="resource-only", scope="peer") - for cross-book links
• Warehouse books (processing-role="resource-only", scope="local") - to con[key]ref content

When we perform an operation that operations on the current DITA Map hierarchy (such as Find in Files or refactoring operations), the operation traverses into every submap, regardless of how it's referenced. However, this is often undesired. For example, Find/Replace operations traverse into tens of thousands of pages of content in maps owned by other writers, when those bookmaps are referenced only for cross-book links.

But in other cases, we might want to traverse into either or both book types, such as searching for content in peer books only or running administrative operations that should include warehouse books only.

We need a way to control whether "Current DITA Map Hierarchy" traverses into each of these book types. Possible checkbox descriptions are:

• Include resource-only maps
• Include peer maps

where a "resource-only" map does not include @scope-"peer" content. Other checkbox descriptions are possible, but the descriptions should be kept as nontechnical writer-friendly as possible. In addition, other categories/restrictions could be included as appropriate.

In addition, we would like to be able to specify the default map traversals for refactoring operations. (We have a separate enhancement request for specifying the default filetypes for refactoring operations, and this is similar to that.)

A testcase is attached. To run,

1. Open the project file.
2. Open the OPEN2.ditamap file.
3. Do a Find in Files for "FINDME" in the current DITA Map hierarchy.
4. Similarly, preview the "Find FINDME" refactoring operation included with the project.

oxygen_refactoring_mapref_scope.zip

[Radu]

Hi Chris,

From what I tested:

1) If in the DITA Maps Manager you refer to a DITA Map with scope=peer (peer-map.ditamap), it is not presented as expanded in the DITA Maps Manager and thus we do not search inside topics referenced by this DITA Map, we do search directly inside "peer-map.ditamap" but we do not go into the topics.
2) If in the DITA Maps Manager you refer to a resource-only DITA Map (warehouse-map.ditamap) it is presented as expanded in the DITA Maps Manager and find/replace works to find content in the topics referenced in it.

Do you get the same behavior on your side? I think both 1 and 2 are correct. Whatever you see in the DITA Maps Manager is searched.

Regards,
Radu

[chrispitude]

Hi Radu,

You are correct! Thank you for double-checking my assertion. It is good that the issue is limited to warehouse books.

I am actually not sure what the best solution is, and I hope you can help me think through it.

Let's say that a warehouse book provides topics A, B, and C (via a resource-only mapref) but we only instantiate topic B in our own book (via a keyref into the warehouse book). There are three possible behaviors a writer might need:

• Include no topics in resource-only maps ("search only MY content that I wrote")
• Include topics locally instantiated from resource-only maps ("search all content in MY book")
• Include all topics in resource-only maps ("search all content available to *MY* book")

I really like the fact that refactoring follows what's visible in the DITA Maps Manager, and I don't want to change that model. But I think we also need to provide some finer scope control here. And I don't know what's technically possible in the software w.r.t. determining which topics are resource-only via a mapref, but then additionally instantiated via a local reference.

What do you think?

[Radu]

Hi Chris,

I added an issue with your ideas "EXM-46703 - Extra scope settings for find/replace in files and XML refactoring in DITA Map", depending on how many other users will request this we'll consider implementing it in a future version.
This particular scope:

Include topics locally instantiated from resource-only maps ("search all content in MY book")

would mean that only topics referenced with keyref in the main DITA Map should be searched, right? But in a way this is similar to "Include no topics in resource-only maps" because topics referenced with keyref are taken into account anyway when they keyrefs are encountered in the main DITA Map.

Regards,
Radu

[chrispitude]

This particular scope:

Include topics locally instantiated from resource-only maps ("search all content in MY book")

would mean that only topics referenced with keyref in the main DITA Map should be searched, right? But in a way this is similar to "Include no topics in resource-only maps" because topics referenced with keyref are taken into account anyway when they keyrefs are encountered in the main DITA Map.

Hi Radu,

You are absolutely right! So it looks like we need a simple way to prevent traversal into resource-only maps from scope dialogs, plus (some day) the ability to set the default for this checkbox in the XML definition of a refactoring operation.

Thanks!

[chrispitude]

After some further thinking... Given the three possible behaviors a writer might need:

1. Include no topics in resource-only maps ("search only MY content that I wrote")
2. Include topics locally instantiated from resource-only maps ("search all content in MY book")
3. Include all topics in resource-only maps ("search all content available to *MY* book")

Scenario 1 differs from scenario 2 in that scenario 1 excludes all topics in resource-only maps, whether they are locally instantiated or not.

My understanding is that scenario 3 is the current behavior today (we traverse into every topic of a resource-only map).

Let's say we have a warehouse book with "Shared Topic 1" and "Shared Topic 2". My own book has "My Topic" that I wrote, and it also instantiates "Shared Topic 1".

• Behavior 1's scope includes only "My Topic".
• Behavior 2's scope includes "My Topic" and "Shared Topic 1".
• Behavior 3's scope includes "My Topic", "Shared Topic 1", and "Shared Topic 2".

All the situations my writers have asked me about correspond to one of these three behaviors. Even with the safety net of Git's Discard Changes, they get very worried when find/replace or refactoring operations modify our warehoused common files (preface, copyright, etc.). And in some cases, we've had writers commit modifications to these warehouse files without realizing it.

I agree that the software mechanics of map visibility don't translate easily into these three behaviors. Right now I'm just trying to establish the writer needs, then we can figure out how to provide them (or determine if we can).

[Radu]

Hi Chris,

Thanks, I will add your extra details to the opened internal issue.

Regards,
Radu

[chrispitude]

To conclude this discussion, Oxygen v24.1 was enhanced earlier this year so that the .ditamap files of @scope="peer" map references are no longer included in the "Current DITA Map Hierarchy" scope. Thank you!