TOC for DITA submap

1
votes

I've came across DITA recently and have been fooling around with it to evaluate if it would be applicable for our internal documentation needs. I'm trying to understand(and learn) how to properly structure the document. My initial setup is something like this:

MainMap.ditamap:

<map>
  <mapref href="submap-1.ditamap"/>
</map>

SubMap-1.ditamap:

<map>
  <topichead navtitle="Topic Title 1">
    <topicref href="topic1.dita"/>
    <topicref href="topic2.dita"/>
  </topichead>
</map>

When I convert this to HTML, I get list of following html:

  • toc.html
  • mainmap.html
  • topic1.html
  • topic2.html

toc.html looks like this:

Table of Contents

  • Topic Title 1
    • topic1
    • topic2

So, one thing I don't understand here is that, "Topic Title 1" is also a link and it is linked to mainmap.html which just contains the title, making it totally useless. I would expect(or want :)) that "Topic Title 1" would not be a link, or, if it is, it would link to a page with TOC for the submap.

  • Is TOC for submaps possible?
  • Should I structure the submaps differently so that the topic title would be more useful? Instead of using topichead, use topicref to a topictitle.dita with summary content and TOC-like list?
    • It would be a bit cumbersome to maintain that list. Is there a way to do this automatically?
  • Convert main map as multi-html page but submap as single-html page? Is that possible?

BTW, I'm trying out evaluation version XMLMind XML Editor - Professional Edition. Suggestion in editor in terms of better functionality/usability/afford-ability is also welcome. :)

Thank you for you assistance!

2
documentationdocumentation-generationxmldocumentdita

2 Answers

1
votes

TOCs for submaps can be generated, it's up to the processor; XMLMind XML Editor uses XMLmind DITA Converter to process DITA.

Semantically, the element should just generate a new hierarchical level with the title. XMLMind DITA Converter seems to process this as if the was a with a title-only topic. For example the DITA Open Toolkit (DITA-OT) would only generate a title in the TOC, not an autogenerated "overview" topic.

Again, for DITA-OT, if you use instead with a overview topic, child links to nested topics will be generated automatically, so you don't have to maintain them manually. See if this is the case for XMLMind DITA Converter too.

WRT. editors for DITA, my personal preference is for oXygen XML Editor. It can be used by developers as well as technical writers, it's under active development and quite affordable.

0
votes

To view the content of submap-1 as an HTML file, convert it from a ditamap to a topic.