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:
Tag di configurazione:
<!ELEMENT extension (toc*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA
#IMPLIED
name CDATA
#IMPLIED
>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary
(true | false) "false"
extradir CDATA #IMPLIED
>
Tag di configurazione del file toc:
<!ELEMENT toc (topic | anchor | link)*
>
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!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 topic (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). 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 link (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 selezione, 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 topic è il percorso ad un file argomento che descrive il TOC. 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.
(nel file plugin.xml).
<extension point="org.eclipse.help.toc"> <toc file="maindocs.html" 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>
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 "Creating Java Project" potrebbe restituire un documento del tipo "Other Ways of Creating Java Project", il cui percorso è samples/sample2.html.
Internazionalizzazione È possibile convertire i file TOC XML e posizionare la copia risultante (con le etichette convertite) nella directory nl/<lingua>/<paese> o nl/<lingua>. <lingua> e <paese> indicano i codici di due caratteri della lingua e del paese, utilizzati nei codici di lingua locale. Ad esempio, le traduzioni in italiano saranno collocate nella directory nl/it/IT. La directory nl/<lingua>/<paese> ha priorità sulla directory nl/<lingua>. Solo se non viene individuato alcun file in nl/<lingua>/<paese>, saranno utilizzati i file della directory nl/<lingua>. La directory principale del plug-in sarà esaminata per ultima.
È 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.
Copyright (c) 2000, 2003 IBM Corporation e altri.
Tutti i diritti riservati. Questo programma e il materiale di accompagnamento
sono disponibili secondo i termini della Common Public License v1.0 che sono
distribuiti con il prodotto, e disponibili all'indirizzo
http://www.eclipse.org/legal/cpl-v10.html