Файлы оглавления (toc)

На основе файлов содержимого можно создать файл оглавления (toc). Файл оглавления задает ключевые точки входа, позволяющие обратиться к файлам содержимого в формате HTML. Для этого метка раздела связывается с ссылкой в одном из файлов HTML.  

Приложения, перенесенные в платформу, могут использовать существующую документацию, определив с помощью файлов оглавления соответствующие точки входа.

В состав модуля может входить произвольное число файлов оглавления. В данном примере документация разделена на три основные категории: Концепции, Задачи и Справочники. Каким образом, создать файлы оглавления, описывающие такую структуру?

В зависимости от того, каким образом группы разработки документации взаимодействуют друг с другом, можно создать один большой файл оглавления, либо несколько файлов - по одному для каждой категории содержимого. Если отдельные категории распределены между разными авторами, рекомендуется для каждой из них создать собственный файл оглавления. Архитектура платформы в данном случае значения не имеет.

Несмотря на небольшое число файлов содержимого, в этом примере для каждой категории информации будет создан отдельный файл оглавления. Предположим, что данный пример создается для большего числа файлов, либо что категории распределены между несколькими авторами.

Файлы оглавления будут выглядеть приблизительно следующим образом:

toc_Concepts.xml

   <toc label="Концепции">
      <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="Задачи">
      <topic id="plainTasks" label="Общая информация">
         <topic label="Task1" href="html/tasks/task1.html"/>
         <topic label="Task2" href="html/tasks/task2.html"/>
      </topic>
      <topic id="funTasks" label="Занимательная информация" >
         <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="Справочники">
      <topic label="Ref1" href="html/ref/ref1.html"/>
      <topic label="Ref2" href="html/ref/ref2.html"/>
   </toc>

В качестве раздела можно указать простую ссылку на содержимое. Например, раздел "Task1" описывается с помощью атрибутов label и href. Кроме того, отдельный раздел может представлять собой иерархическую группировку подразделов без содержимого. Например, для раздела "Занимательная информация" указан только атрибут label и подразделы. Атрибут href отсутствует. Эти два подхода можно совмещать. Для раздела "Concept1" указан как атрибут href, так и подразделы.