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:

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

If you want to combine topics in each other, use the chunk attribute and
specify whether each child topic should appear in the
TOC:

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

Suppose you want to group a set of topics in your map so that all topics in the group inherit
the same attributes and properties. By making the topics children of an element, the
children inherit the parent's properties.

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.

You can also use the topicgroup element to do the same bulk-applying of
attributes. The difference between topichead and
topicgroup is that topichead applies a hierarchy in the
TOC, while topicgroup does not result in any
hierarchy.

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".