Budowanie zagnieżdżonych struktur dokumentacji

Ponieważ moduły dodatkowe dodają funkcje do platformy, powszechne stało się dodawanie dokumentacji opisującej nowe funkcje. Jak powinna wyglądać struktura takiej dokumentacji, aby użytkownik widział spójny i kompletny zestaw dokumentów zamiast wielu pojedynczych elementów? Definicja spisu treści udostępnia mechanizmy pozwalające na dwa podejścia do budowania dokumentacji: zstępujące i wstępujące.

Zagnieżdżanie zstępujące

Zagnieżdżanie zstępujące jest techniką definiowania głównego spisu treści, który odwołuje się do wszystkich pozostałych spisów treści. Jest to wygodna metoda dzielenia treści na mniejsze części. W przypadku zagnieżdżania zstępującego atrybut link jest używany w definicji spisu treści raczej do odwoływania się do dowiązanych spisów treści niż do udostępniania elementu href

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

Podstawowa struktura pozostaje niezmieniona (Pojęcia, Czynności, Odwołania), ale poszczególne spisy treści mogą być zmieniane. One z kolei mogą zawierać odsyłacze do innych podrzędnych spisów treści.

Układ wstępujący

Większa elastyczność układu wstępującego polega na tym, że nowe moduły dodatkowe mogą decydować o położeniu dokumentacji w strukturze spisu treści. Układ wstępujący jest realizowany przy użyciu atrybutów anchor. W pliku spisu treści definiowane są punkty zakotwiczenia o określonych nazwach, w których moduły dodatkowe mogą dodawać dokumentację. W tym przykładzie można dodać punkty zakotwiczenia, aby moduły dodatkowe mogły udostępnić materiał uzupełniający w sekcjach pojęć, czynności i odwołań.

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

Inne moduły dodatkowe mogą dodawać elementy do tego punktu zakotwiczenia. W tym celu w trakcie definiowania spisu treści należy użyć atrybutu link_to.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Najnowsze informacje o pojęciach">
	<topic>
		...
	</topic>
</toc>