Создание вложенных структур документации

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

Нисходящее вложение

Нисходящее вложение представляет собой способ определения главного оглавления, связанного с прочими файлами оглавлений. Это эффективный метод разбиения известного содержимого на меньшие фрагменты. Для реализации нисходящего вложения в определении оглавления вместо атрибута href применяется атрибут link, указывающий на связанные файлы оглавлений.

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Концепции">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Задачи">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Справочники">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

Основная структура остается неизменной (Концепции, Задачи, Справочники), однако отдельные файлы оглавлений могут меняться. Они в свою очередь могут содержать ссылки на другие файлы оглавлений.

Восходящее составление

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

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Концепции">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Задачи">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Справочники">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

С помощью меток другие модули могут предоставить связанную документацию. Для этого в файлах оглавления применяется атрибут link_to.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Последняя информация о концепциях">
	<topic>
		...
	</topic>
</toc>