Update map to reflect nested subtopic structure

[chrispitude]

In DITA, a topic file can contain nested subtopic structure in that same file:

Code: Select all

<topic id="my_topic_id">
  <title>My Topic</title>
  <body>...</body>
  <topic id="my_subtopic1_id">  <!-- nested subtopic -->
    <title>My Subtopic #1</title>
    <body>...</body>
  </topic>
  <topic id="my_subtopic2_id">  <!-- nested subtopic -->
    <title>My Subtopic #2</title>
    <body>...</body>
  </topic>
</topic>

These nested subtopics require corresponding nested topicrefs in the map:

Code: Select all

    <topicref href="my_topic.dita" keys="my_topic">
        <topicref href="my_topic.dita#my_subtopic1_id" keys="my_subtopic1"/>  <!-- nested topicref -->
        <topicref href="my_topic.dita#my_subtopic2_id" keys="my_subtopic2"/>  <!-- nested topicref -->
    </topicref>

A similar requirement exists for glossary term definitions nested in a glossary file:

Code: Select all

    <topicref href="glossary.dita">
        <topicref href="glossary.dita#oxygen_xml_author_id" keys="oxygen_xml_author"/>     <!-- nested topicref -->
        <topicref href="glossary.dita#oxygen_xml_developer_id" keys="oxygen_xml_editor"/>  <!-- nested topicref -->
        <topicref href="glossary.dita#oxygen_xml_editor_id" keys="oxygen_xml_editor"/>     <!-- nested topicref -->
    </topicref>

Without these nested-topic topicrefs,

• Keyrefs to the subtopics or any content within the subtopics cannot be constructed.
• Navigation links to subtopics are missing in in HTML/WebHelp outputs.

To address these issues, it would be useful for Oxygen to create/update topicrefs to nested subtopic structures as needed.

Some challenges exist:

• What if a topic is edited, but one or more map files referencing that topic are not also open for editing? This might require some sort of update operation that is run on a map. Or perhaps the "Main Files" infrastructure could detect when there are map references to a topic being edited, and update them as needed.
• Profiling conditions must be synchronized between subtopic elements and their topicrefs. Otherwise, subtopic links can appear in HTML/WebHelp navigation despite the topic itself not being present, or vice versa.

This is not an easy problem, but it is a problem that is valuable to be solved.

A testcase is attached. To run,

• Open the project file.
• Open the "without" map.
• Publish WebHelp, and note that the subtopics are missing from navigation.
• Attempt to "Paste as link (keyref)" for a subtopic and note that Oxygen gives an error that the item cannot be referenced.
• Open the "with" map and note that both these operations are successful

oxygen_subtopic_structure.zip

[Radu]

Hi Chris,

Thanks for the improvement request, I added an internal issue for this:

EXM-48539 Automatically update topicrefs to nested topics in the DITA Map

I think most people have one topic per file, even with that glossgroup example you can save each glossentry separately to a file.
Right now I see this more of a niche use case, we have not received any previous request for this but maybe in time who knows...

Regards,
Radu

[chrispitude]

Thanks Radu! I appreciate you filing the issue.

We like that the DITA nested topic structure directly controls how the HTML output is chunked. Although DITA attributes are available to control chunking, our writers find them confusing and awkward. They prefer to author content exactly as it will be presented to the users.

They also enjoy the freedom of being able to freely move and restructure subtopic content during editing. Subtopic content within a single file is tightly related by nature. Nested subtopic structure can be freely added/removed/tweaked as part of the discovery experience of authoring, without file mechanics getting in the way.

Another concern is file count. We currently have about 60,000 DITA topic files. If we broke these into individual files per topic, the file count would multiply by several times.

We developed an external tool in Oxygen that patches up map references after a topic is edited. It is slow and clunky (hence the request for a native solution), but the benefit it provides is worth the trouble. If a general solution existed, I think more customers would use this approach.

[ritus]

Hello Radu, Chris,

I want to add my vote to this request.
We have exactly same scenario.

Thanks,
Ritu

[Radu]

Hi Ritu,
I will add your feedback on the already opened internal issue but I'm afraid this is not high priority for us.
Regards,
Radu

[chrispitude]

Hi Ritu,

As I learn more about XSLT, I think it might be possible to develop a refactoring operation that can be run on a map, where it reads topic files during the refactoring operation as sub-documents and incorporates their nested topic structure into the map. This is something I hope to look into over the next few months as time permits.

[ritus]

Thanks Chris.

[chrispitude]

Hello everyone,

With some help from my trusty AI coding agent, I am finally working on a refactoring operation to do this!

But here is the challenge. I designed the XSLT refactoring operation to run only on the root .ditamap file, and it takes responsibility for recursing into all the submap .ditamap files in XSLT. This is because I want to implement "keyref preservation" where if I cut/paste a nested subtopic from one submap scope to another (such as when reorganizing content), the refactoring operation is smart enough to preserve its @keys value in the map domain. To do this preservation across submap scopes, the refactoring operation must see everything from the top down.

The problem is that when I open a map in DITA Maps Manager and run my refactoring operation with a scope of Entire DITA map hierarchy, the XSLT template is run on every submap .ditamap file in the map hierarchy. This is normally a very useful thing for refactoring operations! But it's working against me here in this particular case.

A workaround is to select the root map file itself in the Project view, but our writers will never remember to do this - they are too accustomed to running refactoring operations from the DITA Maps Manager.

Here's a testcase:

print_map_filenames.zip

If you open level1.ditamap in the DITA Maps Manager and run the refactoring operation on the Entire DITA map hierarchy scope, you will see messages like this:

Code: Select all

Description: [Saxon-EE] Processing level1.ditamap
Description: [Saxon-EE] Processing level2.ditamap via level1.ditamap
Description: [Saxon-EE] Processing level3.ditamap via level1.ditamap
Description: [Saxon-EE] Processing level2.ditamap
Description: [Saxon-EE] Processing level3.ditamap via level2.ditamap
Description: [Saxon-EE] Processing level3.ditamap

If I can get this refactoring operation working smoothly and intuitively, I'd love to write a blog post about it!

- Chris

[Radu]

Hi Chris,

Right, the "Entire DITA map hierarchy" scope means that the XSLT operation is run on every reference in the opened DITA Map, being those references maps or topics.
As in the "print-map-filenames.xml" you added the extra filesFilter="*.ditamap" filter, this means that only the DITA map and its referenced submaps get processed.
So this is expected functionality. There is also the "Selected DITA map references" scope if one wants to select the root of the DITA Map and apply the XML refactoring.
Not sure what improvement would need to be added to Oxygen for your particular case. Would knowing the URL of the current DITA Map opened in the DITA Maps Manager view in the XSLTs help? This would help you just copy unchanged the submaps.

Regards,
Radu

[chrispitude]

Thank you Radu! I did not know about the "Selected DITA map references" scope. That might be because it seems to only show up in certain circumstances. In the DITA Maps Manager,

• If I right-click the map root, choose Refactoring > XML Refactoring, then select Update map, I see the "Selected DITA map references" scope.
• If I right-click the map root, then choose Refactoring > Update map (recently used), I do not see it.

Here is a testcase:

primary_map_refactoring.zip

It contains a refactoring operation that updates .ditamap <topicref> structure to match .dita <topic> structure. If a topic or subtopic is moved from one place to another (same-file, cross-file, cross-map), the @keys value is preserved by matching up the <topic> @id attribute value from its old .ditamap reference to its new .dita location.

The stylesheet takes ownership of recursing into submaps to build a comprehensive topic inventory. As a result, it is important that the stylesheet runs only on the top .ditamap file. I think the only safe scope for this refactoring operation is the DITA Maps Manager scope.

I also see issues with Oxygen having difficulty with the output documents from the stylesheet; I think that is orthogonal to the scope challenge.

In the provided testcase, I swapped two subtopics between two .dita files. You can try the steps in the first list item above to reproduce the issues.

The currently refactoring scope display is dynamic and provides the user a lot of intuitive control. Normally this is a great thing. However when a stylesheet has strict scope requirements for correct operation, perhaps the stylesheet could specify the allowed scope (or scopes?) so that it operates properly. Or maybe there are other solutions I am not thinking of?

[Radu]

Hi Chris,
Thanks, the sample project I received was up to your usual high standards
I added an internal issue:
EXM-58031 Missing Selected DITA Map references scope when running recently used XML refactoring action from DITA Maps Manager context menu
Regards,
Radu

[chrispitude]

Awesome, thank you Radu!

I almost hate to ask - do you have any rough estimated fix release in mind?

[Radu]

Hi Chris,
The next Oxygen release: version 29 - November this year.
Regards,
Radu