Update map to reflect nested subtopic structure

Post by **chrispitude** » Tue Aug 03, 2021 9:27 pm

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

<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: (2.96 KiB) Downloaded 184 times

Post by **Radu** » Wed Aug 04, 2021 9:22 am

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

Post by **chrispitude** » Wed Aug 04, 2021 10:39 am

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 · Post by **ritus** » Sun Jul 24, 2022 7:09 pm

Hello Radu, Chris,

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

Thanks,
Ritu

Post by **Radu** » Mon Jul 25, 2022 12:09 pm

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

Post by **chrispitude** » Mon Jul 25, 2022 2:44 pm

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 · Post by **ritus** » Fri Aug 05, 2022 7:55 pm

Thanks Chris.

Update map to reflect nested subtopic structure

Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure

Re: Update map to reflect nested subtopic structure