Construction de structures imbriquées de documentation

Sachant que les plug-ins ajoutent des fonctions à la plate-forme, il est fréquent d'ajouter de la documentation décrivant une nouvelle fonction. Comment structurer la documentation pour que l'utilisateur dispose d'un ensemble complet et cohérent au lieu de contributions multiples ? La définition de la table des matières offre des mécanismes de construction de la documentation de façon ascendante et descendante.

Imbrication descendante

L'imbrication descendante correspond à la technique de définition d'une table des matières principale faisant référence à toutes les autres tables existantes. Il s'agit d'une méthode pratique pour décomposer un contenu en plusieurs éléments. Avec cette approche, l'attribut link est utilisé dans la table des matières pour faire référence aux tables liées au lieu de fournir un argument href

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tâches">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Référence">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

La structure de base est inchangée (Concepts, Tâches, Référence), mais les tables individuelles peuvent évoluer à leur guise. Elles peuvent à leur tour être liées à d'autres tables.

Composition ascendante

La composition ascendante offre plus de souplesse car elle permet à de nouveaux plug-ins de décider à quel endroit la documentation doit se trouver dans la structure. Cette composition s'effectue à l'aide d'attributs anchor. Une table des matières définit des points d'ancrage nommés où des plug-ins peuvent ajouter de la documentation. Dans notre exemple, il est possible d'ajouter des ancres pour que des plug-ins ajoutent des données entre les concepts, les tâches et les références.

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tâches">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Référence">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

D'autres plug-in peuvent contribuer à l'ancre à partir de leur propre plug-in. Dans ce cas, l'attribut link_to est utilisé lors de la définition d'une table des matières.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Informations de dernière minute sur les concepts">
	<topic>
		...
	</topic>
</toc>