Als u met een plugin een nieuwe functie aan het platform toevoegt, is het gebruikelijk om ook documentatie toe te voegen waarin u de nieuwe functie beschrijft. Hoe kunt u deze documentatie zo structureren dat de gebruiker een overzichtelijke en volledige documentatieset ziet in plaats van allerlei afzonderlijke bijdragen? De inhoudsopgavedefinitie biedt u zowel de mogelijkheid om de documentatie van boven naar beneden (top-down) als van beneden naar boven (bottom-up) op te bouwen.
Bij van boven naar beneden nesten definieert u een master-inhoudsopgave waarin wordt verwezen naar alle onderliggende inhoudsopgaven. Dit is een handige methode om bekende content onder te verdelen in kleinere stukken. Bij van boven naar beneden nesten gebruikt u in de inhoudsopgavedefinitie het kenmerk link (in plaats van href) om naar bijbehorende inhoudsopgaven te verwijzen.
<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>
De basisstructuur blijft hetzelfde (Concepts, Tasks en Reference: concepten, taken en naslaginformatie), maar de afzonderlijke inhoudsopgaven kunnen vrijelijk worden uitgebreid. Deze kunnen op hun beurt weer worden gekoppeld aan andere subinhoudsopgaven.
Samenstelling van beneden naar boven biedt meer flexibiliteit omdat hierbij in elke nieuwe plugin kan worden aangegeven waar de documentatie in de inhoudsopgavestructuur moet worden opgenomen. Samenstelling van beneden naar boven geschiedt met behulp van anchor-kenmerken (ankers). Hiertoe worden in de inhoudsopgave benoemde ankerpunten gedefinieerd waar andere plugins documentatie kunnen aanleveren. Zo kunt u in het voorbeeld enkele ankers toevoegen zodat plugins aanvullend materiaal kunnen aanleveren tussen de secties Concepts, Tasks en Reference (concepten, taken en naslaginformatie).
<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>
Andere plugins kunnen vervolgens op de plaats van het anker aanvullende documentatie aanleveren vanuit de bijbehorende plugin. Dit kan met het kenmerk link_to tijdens de definitie van een inhoudsopgave.
<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Recente informatie over concepten"> <topic> ... </topic> </toc>