Creazione di strutture di documentazione nidificate

Man mano che i plugin forniscono funzioni aggiuntive alla piattaforma, è frequente che venga aggiunta documentazione per descrivere tali nuove funzioni.  Come organizzare questa documentazione in modo che l'utente possa disporre di una struttura coerente e completa anziché di tanti singoli contributi?  La definizione del sommario (toc) offre un insieme di utili sistemi per organizzare la documentazione in base a una struttura verticale di livelli che procede dal basso verso l'alto e viceversa.

Nidificazione dall'alto verso il basso

La nidificazione dall'alto verso il basso è una tecnica di definizione di un toc principale che consente di fare riferimento a tutti gli altri toc inclusi.  Si tratta di un metodo estremamente conveniente per suddividere contenuto noto in un insieme di elementi di dimensioni inferiori.  Con questo tipo di nidificazione, l'attributo link viene utilizzato nella definizione del sommario per fare riferimento ai toc collegati piuttosto che per fornire un 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>

La struttura di base rimane invariata (Concetti, Attività, Riferimento), ma i singoli toc sono liberi di evolversi.  Possono a loro volta collegarsi ad altri toc secondari.

Nidificazione dal basso verso l'alto

La nidificazione dal basso verso l'alto è più flessibile poiché consente ai nuovi plugin di decidere dove posizionare la documentazione nella struttura toc.  Tale metodo viene applicato utilizzando attributi anchor.  Un toc definisce punti di ancoraggio denominati in cui altri plugin possono fornire documentazione.  Nell'esempio riportato di seguito, è possibile aggiungere nuovi attributi anchor in modo che i plugin possano fornire materiale supplementare tra le sezioni relative ai concetti, alle attività e ai riferimenti.

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

Altri plugin possono quindi fornire aggiunte all'anchor dal loro plugin.  A tale scopo è necessario utilizzare l'attributo link_to nella definizione di un toc.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Late breaking info about concepts">
	<topic>
		...
	</topic>
</toc>