Update map to reflect nested subtopic structure

Are you missing a feature? Request it's implementation here.
chrispitude
Posts: 336
Joined: Thu May 02, 2019 2:32 pm

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:

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

Radu
Posts: 7592
Joined: Fri Jul 09, 2004 5:18 pm

Re: Update map to reflect nested subtopic structure

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

chrispitude
Posts: 336
Joined: Thu May 02, 2019 2:32 pm

Re: Update map to reflect nested subtopic structure

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.

Post Reply