Table of contents (toc) files
Now that we have our sample content files we can create a table of contents (toc)
file. A toc file defines the key entry points into the HTML content files by mapping a topic
label to a reference in one of the HTML files.
Applications that are being migrated to the platform can reuse existing documentation by
using the toc file to define entry points into that documentation.
A plug-in can have one or more toc files. Our example documentation is organized into three main categories: concepts, tasks and reference. How do we make
toc files that represent this structure?
We could make one large toc file, or we could create a separate toc file for each main category of content. This decision should be made according to the way your documentation teams work together.
If a different author owns each category, it might be preferable to keep
separate toc files for each category. It is not dictated by the platform architecture.
In this example, we will create a toc file for each major content category. For such a small number of files,
having separate toc files for each category may not be necessary. We
will build this example as if we had many more files or had separate authors who
own each content category.
Our files look like this:
toc_Concepts.xml
<toc label="Concepts">
<topic label="Concept1" href="html/concepts/concept1.html">
<topic label="Concept1_1" href="html/concepts/concept1_1.html"/>
<topic label="Concept1_2" href="html/concepts/concept1_2.html"/>
</topic>
</toc>
toc_Tasks.xml
<toc label="Tasks">
<topic id="plainTasks" label="Plain Stuff">
<topic label="Task1" href="html/tasks/task1.html"/>
<topic label="Task2" href="html/tasks/task2.html"/>
</topic>
<topic id="funTasks" label="Fun Stuff" >
<topic label="Task3_1" href="html/tasks/task3_1.html"/>
<topic label="Task3_2" href="html/tasks/task3_2.html"/>
</topic>
</toc>
toc_Ref.xml
<toc label="Reference">
<topic label="Ref1" href="html/ref/ref1.html"/>
<topic label="Ref2" href="html/ref/ref2.html"/>
</toc>
A topic can be a simple link to content.
For example, "Task1" provides a label
and an href linking to the content. A
topic can also be a hierarchical grouping of sub topics with no content of its
own. For example, "Fun Stuff" has only a label
and sub topics, but no href . Topics can
do both, too. "Concept1" has an href
and sub topics.
Dynamic content
Dynamic content is available for the table of contents in the form of
filters and
extensions. For example, you may want a topic to show up in the table of contents
only when running on a specific operating system.
Includes are not supported here because they
are not needed; use
links instead.
