HTML5: nested topics do not appear in ToC

[pflotscher]

Description

This issue has already been brought up but was marked as stale. See #3428. It also shows an example.
I know this is because of the ToC mechanism being based on @class, ' map/topicref ', so there is no information for the ToC about nested topics.
I would like to open a discussion about this since org.dita.pdf2 recognizes nested topics and puts them in the ToC and I would consider this as unexpected behaviour of org.dita.html5.
Please correct me if I'm missing out on something here.

Possible Solution

Open for ideas, I haven't found a solution so far.

[chrispy-snps]

@pflotscher - we are heavy users of nested subtopics. We like that the DITA topic/subtopic structure directly corresponds to the HTML topic structure, which allows our technical writers to craft the customer content experience that they want (no topic merging/splitting during transformation).

We explicitly include nested subtopic references in our maps:

<topicref href="path/to/topic.dita" keys="topic">
  <topicref href="path/to/topic.dita#subtopic1" keys="subtopic1">
    <topicref href="path/to/topic.dita#subsubtopic" keys="subsubtopic"/>
  </topicref>
  <topicref href="path/to/topic.dita#subtopic2" keys="subtopic2"/>
</topic>

We also use keys, so we need these explicit topic references to specify the key values.

Adding these explicit subtopic references is a bit of a pain for the technical writers. If you are using Oxygen, you might also want to put your support behind this issue:

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

[jelovirt]

This feature would need to be under a toggle, because we don't want to break backwards compatibility.

[chrispy-snps]

@pflotscher - do you use topic keys and keyrefs in your flow?

[chrispy-snps]

@pflotscher - your request is reasonable, considering that the pdf2 transform does include implicit nested subtopics in its TOC.

If it makes you feel better in the meantime, explicit nested topic references are normal for those of us that use keys and keyrefs, so they are not inherently bad or inelegant if you update your DITA XML generation to generate them.

Regarding your reply item 1, if a nested topic has no explicit reference, the topic content is generated but the HTML TOC entry is not.

Regarding your reply item 2, that is indeed the tricky part! Oxygen has a graphical map view (called the DITA Maps Manager) that nicely shows topic/subtopic structure and key values. But currently, it does not automatically search inside topics for unreferenced subtopics. That is not an easy problem because users can do thinks like rearrange subtopics and even move them from one file to another, and ideally a best-effort attempt should be made to keep their key values in the process.