Sisäkkäisten dokumentaatiorakenteiden koonti

Kun lisäosat lisäävät ympäristöön toimintoja, on tavanomaista lisätä dokumentaatiota, joka kuvaa uusia toimintoja. Kuinka tämän dokumentaation voi jäsentää siten, että käyttäjä saa nähtäväkseen yhtenäisen ja kokonaisen dokumentaation eikä useita yksittäisiä lisäyksiä? Sisällysluettelon määrityksissä on keinoja koota dokumentaatio joko ylhäältä alas tai alhaalta ylös.

Sisäkkäisyys ylhäältä alas

Ylhäältä alas suuntautuva sisäkkäisyys tarkoittaa menetelmää, jossa määritetään pääsisällysluettelo, joka viittaa kaikkiin sisällytettäviin sisällysluetteloihin. Ylhäältä alas suuntautuva sisäkkäisyys on kätevä tapa jakaa tunnettu sisältö pienempiin osiin. Ylhäältä alas suuntautuvassa sisäkkäisyydessä link-määritettä käytetään sisällysluettelon määrityksessä viittaamaan linkitettyihin sisällysluetteloihin, ei href-tunnistetta. 

<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>

Perusrakenne säilyy samana (Käsitteet, Tehtävät, Ohjeet), mutta yksittäiset sisällysluettelot pääevät muotoutumaan vapaasti. Ne voivat puolestaan linkittyä muihin alisisällysluetteloihin.

Koostaminen alhaalta ylös

Alhaalta ylös suuntautuva koostaminen on joustavampaa, koska se sallii uusien lisäosien määrittää, minne dokumentaatio sijoittuu sisällysluettelon rakenteessa. Koostaminen alhaalta ylös toteutetaan anchor-määritteiden avulla. Sisällysluettelo määrittää nimettyjä ankkuripisteitä, joihin muut lisäosat voivat lisätä dokumentaatiota. Tässä esimerkissä voitaisiin lisätä ankkureita niin, että lisäosat voivat lisätä aineistoa käsitteiden, tehtävien ja ohjeiden osioihin.

<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>

Muut lisäosat voivat sitten lisätä aineistoa ankkuriin lisäosastaan.  Tämä tehdään link_to-määritteen avulla sisällysluettelon määrityksen yhteydessä.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Viimeisimmät tiedot käsitteistä">
	<topic>
		...
	</topic>
</toc>