Descrizione: consente di registrare un contributo della guida in linea per un singolo plug-in.
Ciascun plug-in che contribuisce con file della guida dovrebbe eseguire le seguenti azioni:
<!ELEMENT toc EMPTY>
<!ATTLIST toc file CDATA #REQUIRED>
<!ATTLIST toc primary (true | false) "false">
<!ATTLIST toc extradir CDATA #IMPLIED>
<!ELEMENT toc (topic | anchor | link)*
>
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ELEMENT topic (topic | anchor | link )*
>
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
<!ELEMENT anchor EMPTY >
<!ATTLIST anchor id ID #REQUIRED
>
<!ELEMENT link EMPTY >
<!ATTLIST link toc CDATA #REQUIRED >
In termini generali, un plug-in che deve fornire la Guida in linea, definisce i propri file TOC. Alla fine, il sistema della guida è configurato in modo da poter essere avviato come un'azione mediante il percorso del file TOC.
L'elemento argomento
Tutti gli elementi argomento della guida vengono forniti come parte dell'elemento contenitore del toc. Possono avere una struttura gerarchica o essere semplicemente elencati.
L'elemento argomento è il motore della struttura del Sommario (TOC, Table of Contents). Esistono due utilizzi tipici dell'elemento argomento:
1. Fornire un collegamento a un file di documentazione (generalmente, un file HTML).
2. Fungere da contenitore per altri sommari, nello stesso o in un altro manifest.
1. Argomenti come collegamenti
L'utilizzo più semplice di un argomento è quello di servire da collegamento a un file di documentazione.
<topic label="Some concept file" href="concepts/some_file.html" />
L'attributo href è relativo al plug-in a cui appartiene il file manifest. L'utente può utilizzare la sintassi per accedere a un file in un altro plug-in.
<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Argomenti come contenitori
Un altro utilizzo più frequente di un argomento consiste nel fungere da contenitore per altri sommari. Lo stesso argomento contenitore può sempre fare riferimento a un file particolare.
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
L'elemento collegamento
Questo elemento consente il collegamento al Sommario definito in un altro file toc. Tutti gli argomenti del file toc specificati nell'attributo toc verranno visualizzati nel sommario come se fossero definiti direttamente al posto dell'elemento collegamento. Per includere il sommario dal file api.xml è possibile scrivere
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
L'elemento anchor
L'elemento anchor definisce un punto che consente di collegare altri file toc a questa navigazione, consente inoltre di estendere il punto senza utilizzare l'elemento collegamento e fare riferimento ad altri file toc da qui. Per consentire l'inserimento di più argomenti nel Sommario dopo il documento "ZZZ" è necessario definire un anchor nel seguente modo:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
L'elemento toc
L'elemento toc è un Sommario che raggruppa argomenti e altri elementi definiti in questo file. Quando viene visualizzata, l'etichetta identifica il sommario per l'utente. L'attributo opzionale link_to consente il collegamento del toc in un altro file toc di livello superiore nella gerarchia di navigazione. Il valore dell'attributo link_to deve specificare un anchor in un altro file toc. Per collegare il toc dal file myapi.xml al file api.xml, specificato in un altro plug-in, utilizzare la sintassi
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
dove il carattere # separa il nome del file toc dall'identificativo dell'anchor.
Esempi:
di seguito viene riportato un esempio di utilizzo del punto di estensione toc. Si supponga che sia riferito a un plug-in con un id denominato "org.eclipse.help.examples.ex1". L'esempio è generale ed è necessario osservare che la stessa gerarchia di documentazione, che risulta da tutti i seguenti file toc, potrebbe essere creata anche mediante varie combinazioni di altri file toc.
(nel file plugin.xml).
<extension point="org.eclipse.help.toc">
<toc file="maindocs.xml" primary="true" />
<toc file="task.xml" />
<toc file="sample.xml" extradir="samples" />
</extension>
(nel file maindocs.xml)
<toc label="Help System Example">
<topic label="Introduction" href="intro.html"/>
<topic label="Tasks">
<topic label="Creating a Project" href="tasks/task1.html">
<topic label="Creating a Web Project" href="tasks/task11.html"/>
<topic label="Creating a Java Project" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Testing a Project" href="tasks/taskn.html"/>
</topic>
<topic label="Samples">
<topic label="Creating Java Project" href="samples/sample1.html">
<topic label="Launch a Wizard" href="samples/sample11.html"/>
<topic label="Set Options" href="samples/sample12.html"/>
<topic label="Finish Creating Project" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(nel file tasks.xml)
<toc label="Building a Project">
<topic label="Building a Project" href="build/building.html">
<topic label="Building a Web Project" href="build/web.html"/>
<topic label="Building a Java Project" href="build/java.html"/>
</topic>
</toc>
(nel file samples.xml)
<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
<topic label="The Compile Tool Sample" href="compilesample/example.html">
<topic label="Step 1" href="compilesample/step1.html"/>
<topic label="Step 2" href="compilesample/step2.html"/>
<topic label="Step 3" href="compilesample/step3.html"/>
<topic label="Step 4" href="compilesample/step4.html"/>
</topic>
</toc>
Nell'immagine viene illustrata la gerarchia di documentazione che viene visualizzata nel workbench di Eclipse:
Presupponendo che esistano più documenti che abbiano il percorso che inizia con "samples", questi non verranno visualizzati nella struttura di esplorazione, ma saranno accessibili con la funzione di ricerca. Ciò è dovuto alla presenza dell'attributo "extradir" nell'elemento <toc file="sample.xml" extradir="samples" /> all'interno del file plugin.xml. Ad esempio, la ricerca di "Creazione di progetti Java" potrebbe restituire un documento del tipo "Altri sistemi per la creazione di progetti Java", il cui percorso è samples/sample2.html.
E possibile localizzare la documentazione contenuta nel pacchetto doc.zip mediante la creazione di un file doc.zip con la versione tradotta dei documenti da posizionare nella directory
nl/<lingua>/<paese> o nl/<lingua>. Il sistema
della Guida ricercherà i file in queste directory prima di impostare come predefinita la directory plugin.
Informazione API: per utilizzare questo punto di estensione, non è necessario alcun codice. Occorre soltanto fornire i file manifest appropriati, menzionati nel file plugin.xml.
Implementazione fornita: L'implementazione predefinita dell'interfaccia utente del sistema della guida, in dotazione con la piattaforma Eclipse, supporta completamente il punto di estensione toc.