DITA: Map file (table of contents)

Creating a TOC

 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>

 <topicref href="toc_links.dita">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>
</topicref>

Now the toc_inks.dita file (note the lack of the self-closed angle bracket "/>") will be the parent and the 4 links below it will be children. The parent topic will show the four child topics as embedded links along the shortdesc element from each child topic. Essentially the toc_links.dita file is blank and is filled with a preview of the other files nested below it. This is a general best practice for organizing the TOC.

Note that there is another element called a topichead that also allows you to group topics into hierarchical relationships, like this:

<topichead navtitle="Links">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>
</topichead>

However, many people are opposed to using topichead because it creates a containing folder that does nothing except expand its folder contents when a user clicks it. There's a chance that users may think something isn't working, since clicking an option in the menu doesn't create any change in the main viewing window.

Regardless of the usability issue, it's a good idea to present a preview of the folder's contents on the parent topic anyway. This lets the user browse all the topics in the folder with one glance.

Combining topics

 <topicref href="inserting_links.dita" chunk="to-content">
 <topicref href="inline_links.dita" toc="no"/>
 <topicref href="related_links.dita" toc="no"/>
 <topicref href="keyref_links.dita" toc="no"/>
</topicref>

This output will show Inserting Links as the topic title and the three child topics as subheadings within the topic. It will appear as one file. However, note that if you put inserting_links.dita into a relationship table, the related links will appear directly below the first topic rather than after keyref_links.dita. (Some Open Toolkit people want to decouple topics in the relationship table to allow for more granular relationships; however, I think this is a bug that should be fixed.)

Folder structure

All topics that the map file references need to be in either the same directory as the map or in a subdirectory to the map. Don't reference a topic outside of the map's directory (using ../ syntax).

I think it's easiest to leave all dita files loose in the root folder rather than organizing them into subfolders. Reason being, if you decide to reorganize your files, links to subfolder_a/sample.dita will break when you move sample.dita to subfolder_b.

To maintain some sense or order for loosely coupled files, you can begin the file name with the folder name. Alternatively, if you're on a Mac, you can use virtual folders by tagging the files with folder-like names.

For glossary entries, images, or other files clearly of a different format, using subfolders is probably a good idea.

Editing ditamap files

You can more easily arrange the topics in your ditamap file using the DITA Maps Manager feature in Oxygen. This is the panel that appears on the left of the main window. Right-click your ditamap file tab and select Open in DITA Maps Manager.

Through the DITA Maps Manager, you can easily see if a topic is invalid, as it will include a red exclamation mark next to it. Parent-child hierarchies are also formatted with expand/collapse displays. You can see profiling conditions, edit properties, set parent-child hierarchies, and do other things through the Maps Manager.

Applying attributes to groups of elements

 <topichead audience="field_engineers" navtitle="Resources">
  <topicref href="concept.dita"/>
  <topicref href="notes.dita"/>
  <topicref href="conref.dita"/>
 </topicgroup>

Now concept.dita, notes.dita, and conref.dita will all have the attribute audience="field_engineers". These topics will appear inside a folder called Resources.

 <topicref href="toc_links.dita" audience="field_engineers">
  <topicref href="concept.dita"/>
  <topicref href="notes.dita"/>
  <topicref href="conref.dita"/>
 </topicref>

In this example, all the topics in this group will have the audience="field_engineers" attribute applied to them. If you want to apply a grouping independent of any hierarchy, use the topicgroup element.

Linking to non-TOC files

You probably want to link a couple of other files from your ditamap: your notes file (where you store all your conrefs), your relationship table, and your glossary. You could combine them all in the same map, but doing so will make the ditamap file long. When you add these non-TOC links, add an attribute of processing-role:"resource only".

  <topicref processing-role="resource-only" href="notes.dita" />
  <mapref processing-role="resource-only" href="keys.ditamap"/>
  <mapref processing-role="resource-only" href="relationship_table.ditamap"/> 

Notice that I used mapref here instead of topicref. If you use topicref and point to a ditamap file, add format="ditamap" in your attributes.

Additionally, if you're linking to a ditamap, use mapref instead of topicref. If you do use topicref, you must remember to add the format="ditamap" attribute.