Sommario (TOC)

Identificativo: org.eclipse.help.toc

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 del punto di estensione toc (contenuto nel file plugin.xml):

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

Tag di configurazione del sommario (contenuto nel file TOC):

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

Esempio di guida

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.

Internationalization

E possibile tradurre i file TOC XML e posizionare la copia risultante (con etichette tradotte) nella directory nl/<lingua>/<paese> o nl/<lingua>.  Per <lingua> e <paese> si intendono i codici a due lettere relativi alla lingua e ai paesi utilizzati in codici locali.  Ad esempio, le traduzioni dal cinese mandarino dovrebbero essere poste nella directory nl/zh/TW.  La directory nl/<lingua>/<paese> ha una priorità più elevata della directory nl/<lingua>.  I file posizionati in nl/<lingua> saranno utilizzati soltanto se non viene trovato alcun file in nl/<lingua>/<paese>.  Infine sarà ricercata la directory principale di un plug-in.

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.


Copyright IBM Corp. e altri 2000, 2002. Tutti i diritti riservati.