Sestavení vnořených struktur dokumentace

Jelikož moduly plug-in vkládají do platformy funkci, je běžné přidávat dokumentaci, která tuto novou funkci popisuje.  Jak strukturovat tuto dokumentaci tak, aby se uživateli zobrazila soudržná a kompletní sada dokumentace namísto množství jednotlivých příspěvků?  Tabulka definic obsahu poskytuje mechanizmy k sestavení dokumentace jak shora dolů, tak zdola nahoru.

Vnoření shora dolů

Vnoření shora dolů znamená techniku definování položek hlavního obsahu, které se odkazují na všechny ostatní obsažené obsahy.  Vnoření shora dolů je pohodlnou metodou na rozdělení známého obsahu na menší části. Při použití vnoření shora dolů se používá atribut link v definicích položek obsahu k odkazování na propojené obsahy namísto použití href

<toc label="Příklad online nápovědy" 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>

Základní struktura zůstává stejná (Koncepty, Úlohy, Odkazy), ale jednotlivé obsahy je možné dále vyvíjet.  Mohou naopak obsahovat propojení na jiné vnořené obsahy.

Kompozice zdola nahoru

Kompozice zdola nahoru je tvárnější v tom, že nechává na nových modulech plug-in rozhodnutí, kde ve struktuře obsahů by měla dokumentace existovat.  Kompozice zdola nahoru se dosahuje pomocí atributů anchor.  Obsah definuje pojmenované počáteční body, kde mohou ostatní moduly plug-in vkládat dokumentaci.  V našem příkladu bychom mohli přidat počáteční body (kotvy) tak, aby moduly plug-in mohly vkládat další materiál mezi sekce konceptů, úloh a odkazů.

<toc label="Příklad online nápovědy" 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>

Další moduly plug-in pak mohou přispívat ke kotvě z jejich modulu plug-in.  To se provede pomocí atributu link_to při definování obsahu.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Nejnovější důležité informace o konceptech">
	<topic>
		...
	</topic>
</toc>