Bygga nästlade dokumentationsstrukturer

Insticksprogram lägger till funktioner till plattformen, och då är det vanligt att lägga till dokumentation som beskriver den nya funktionen.  Hur kan den dokumentationen struktureras så att användaren får se en konsekvent och fullständig uppsättning dokumentation istället för många separata bidrag?  Definitionen i innehållsförteckningen tillhandahåller mekanismer för att bygga dokumentation både nedifrån och uppifrån.

Nästling i fallande ordning

Nästling i fallande ordning refererar till tekniken att definiera huvudinnehållsförteckningen som refererar till alla inkluderade innehållsförteckningar.  Nästling i fallande ordning är ett praktiskt sätt att dela upp känt innehåll i mindre delar.  Med nästling i fallande ordning används attributet link i definitionen för innehållsförteckningen till att refereratill länkade innehållsförteckningar istället för att href används. 

<toc label="Exempel på onlinehjälp" topic="html/book.html">
	<topic label="Koncept">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Åtgärder">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Referens">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

Grundstrukturen förblir densamma (koncept, åtgärder, referens), men de enskilda innehållsförteckningarna får utvecklas.  De i sin tur kan länka till andra underordnade innehållsförteckningar.

Komposition nerifrån och upp

Komposition nerifrån och upp är mer flexibel i och med att nya insticksprogram själva får avgöra var dokumentationen får ligga i innehållsförteckningsstrukturen.  Komposition nerifrån och upp utförs med hjälp av anchor-attribut.  En innehållsförteckning definierar namngivna ankarpunkter där andra insticksprogram kan tillhandahålla dokumentation.  I vårt exempel skulle vi kunna lägga till ankare så att insticksprogram tillhandahålla ytterligare material mellan koncept-, åtgärds- och referensavsnitten.

<toc label="Exempel på onlinehjälp" topic="html/book.html">
	<topic label="Koncept">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Åtgärder">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Referens">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

Andra insticksprogram kan sedan bidra till ankaret.  Det görs genom att använda attributet link_to när en innehållsförteckning definieras.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Ny information om koncept">
	<topic>
		...
	</topic>
</toc>