Ciascun plugin che contribuisce con file della guida dovrebbe eseguire le seguenti azioni:
Facoltativamente, un indice di ricerca può essere pregenerato e registrato utilizzando l'elemento index
per
migliorare le prestazioni della prima ricerca. Può essere registrato solo un indice per plugin; più elementi index
possono
causare un comportamento imprevisto.
<!ELEMENT extension (toc* , index?)>
<!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 plugin 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). 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 plugin a cui appartiene il file manifest. L'utente può utilizzare la sintassi per accedere a un file in un altro plugin
<topic label="topic in another plugin" 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 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 plugin, 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.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Dalla versione 3.1) un elemento facoltativo che consente la dichiarazione di un indice di ricerca pregenerato creato in base ai documenti forniti da questo plugin.
index/
,
nl/ja/JP/index/
, nl/en/US/index/
, ecc.).(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"
/>
<index path=
"index/"
/>
</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 plugin 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.
Copyright (c) 2000, 2005 IBM Corporation e altri.
Tutti i diritti riservati. Questo programma e il materiale di accompagnamento sono disponibili secondo i termini della Eclipse Public
License v1.0 che sono distribuiti con il prodotto, e disponibili all'indirizzo
http://www.eclipse.org/legal/epl-v10.html