Nota: il sistema della guida è ancora in fase di sviluppo e potrebbe subire delle modifiche prima di diventare stabile. È stato reso disponibile in questo stadio per sollecitare commenti e suggerimenti dai primi utenti, nella convinzione che possano fornire apporti decisivi al suo sviluppo. |
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 topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)* ) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
Tag di configurazione degli infoset(contenuto nel file manifest di infoset):
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset label CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
Tag di configurazione delle azioni di inserimento (contenuto nel file manifest delle azioni):
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
In termini generali, un plug-in, che deve fornire la Guida in linea, definisce i manifest dei propri argomenti e quelli delle azioni necessarie per collegare correttamente gli argomenti. Alla fine, il sistema della guida è configurato in modo da poter essere avviato come un'azione mediante l'id dell'insieme di informazioni.
Un plug-in può utilizzare quattro tipi di elementi XML: l'argomento, l'infoset, le azioni e gli elementi di inserimento.
L'elemento argomento
Per quanto riguarda gli elementi argomenti, tutti gli argomenti vengono forniti come parte dell'elemento contenitore degli argomenti. Possono avere una struttura gerarchica o essere semplicemente elencati. Un manifest degli argomenti è visualizzato come un origine dati per l'interfoliazione di ulteriori argomenti e l'organizzazione in una rete integrata. Inoltre, è possibile eseguire gli argomenti specificandone l'id, ma è anche possibile eseguire un gruppo di argomenti specificando l'id degli argomenti contenuti o dell'elemento argomento. Successivamente, al momento di collegare gli argomenti sulle visualizzazioni o ad altri argomenti, viene mantenuta la struttura definita nel manifest degli argomenti (soggetta a subire modifiche a causa delle azioni di inserimento).
L'elemento argomento è il motore della struttura di esplorazione. Esistono tre utilizzi tipici dell'elemento argomento:
1. Fornire un collegamento a un file di documentazione (generalmente, un file HTML).
2. Fungere da contenitore per altri argomenti, nello stesso o in un altro manifest.
3. Fornire un punto di inserimento per altri argomenti, 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
Il secondo utilizzo più frequente di un argomento consiste nel fungere da contenitore per altri argomenti. 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>
3. Argomenti come punti di inserimento
Gli argomenti possono essere utilizzati come punti di inserimento. Forniscono un luogo logico attraverso il quale gli altri argomenti possono essere testati e uniti. Per potere fungere da punto di inserimento, l'argomento deve possedere un attributo id.
L'elemento infoset
Un set di informazioni costituisce un punto di ingresso nella rete della documentazione. Può essere immaginato come un insieme di visualizzazioni.
Le visualizzazioni sono volte a fornire raggruppamenti semantici di livello elevato nella rete della documentazione. Sono definite mediante l'elemento infoview definito all'interno di un infoset. Un team di documentazione potrebbe utilizzare una visualizzazione per creare una guida introduttiva, attività e sezioni di riferimenti (o altre visualizzazioni definite dal team del prodotto). Sulla piattaforma non vengono specificate le sezioni reali, ma soltanto il relativo meccanismo di definizione.
Ad esempio, potrebbe essere definita una visualizzazione "attività", della quale fanno parte tutti gli argomenti tratti da una prospettiva relativa alle istruzioni di esecuzione di un'operazione. È anche possibile definire un'altra visualizzazione "componente": una struttura degli argomenti in cui sono visualizzati tutti i componenti e la relativa documentazione.
L'elemento infoview costituisce un contenitore degli argomenti che possono essere condivisi da più plug-in. Consente di avere una prospettiva dell'intero documento. A volte alcuni plug-in differenti potrebbero contribuire allo stesso componente logico della documentazione. La presenza di questo elemento assicura che i plug-in vengano correttamente fusi in un insieme coerente durante una visualizzazione "componente".
L'elemento azioni
Il manifest delle azioni contiene le azioni di scripting da eseguire su argomenti e visualizzazioni. Attualmente esiste un solo tipo di azione, l'azione di inserimento, che consente di scrivere argomenti e visualizzazioni in modo tale da creare una rete di informazioni integrata provvista di più visualizzazioni.
Le azioni sono azioni strutturali (inserimento) e, perciò, si applicano a una specifica infoview. Conseguentemente, tutte le azioni di inserimento di un manifest creano la gerarchia degli argomenti in una infoview.
L'elemento inserimento
Uno degli aspetti più complicati di un'esplorazione formata da componenti consiste nel creare una struttura informativa integrata con un flusso continuo. Per crearla, è necessario un meccanismo attraverso il quale sia possibile pubblicare i punti di inserimento, scegliere quale punto di inserimento utilizzare e indicare dove si desiderano inserire gli argomenti (principale, secondario, precedente, successivo).
I punti di inserimento possono essere costituiti da argomenti o visualizzazioni. Un argomento può essere utilizzato come punto di inserimento grazie al relativo id. Le visualizzazioni devono possedere il proprio id. Vengono utilizzati come riferimenti soltanto id completi. Ad esempio, l'id argomento completo di <topic id="concepts" label="concepts"> nel plug-in org.eclipse.help.examples.ex1 è rappresentato da org.eclipse.help.examples.ex1.concepts.
Poiché i punti di inserimento generalmente si trovano in altri plug-in, che potrebbero non essere installati, è possibile specificare un punto di inserimento alternativo. Per impostazione predefinita, l'argomento rimane nella relativa gerarchia componente, quando è impossibile effettuare scelte. L'attributo "to" specifica il punto di inserimento di destinazione. L'argomento specificato dall'attributo "from" rappresenta l'argomento da inserire. Di seguito sono riportate alcune modalità mediante cui è possibile inserire un argomento, che sono specificate utilizzando l'attributo "as":
Vengono fornite anche opzioni di inserimento alternative da eseguire nel caso in cui quelle precedenti non possano essere utilizzate. Queste alternative sono fornite dai sottoelementi nidificati dell'elemento di inserimento. Il sistema può essere immaginato come un meccanismo di riserva dove viene eseguita un'azione di inserimento nidificato ogni qualvolta l'azione di inserimento non riesce. Dopo che l'inserimento è stato eseguito sul primo punto scelto, gli altri punti alternativi vengono ignorati.
Esempi:
di seguito viene riportato un esempio di utilizzo del punto di estensione contributions. 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 file del seguente contributo, potrebbe essere creata anche mediante varie combinazioni di argomenti e file di azioni
(nel file plugin.xml).
<!-- Utilizzare il punto di estensione di contribuzione al sistema della guida per definire infoset, argomenti -->
<!--e file di azioni. Per maggiore chiarezza, il punto di estensione è utilizzato -->
<!-- due volte: una volta per definire l'infoset con la relativa visualizzazione; un'altra volta per definire gli -->
<!-- argomenti e le corrispondenti azioni associate.
-->
<extension point="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<topics name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- Configurare il contributo della guida a questo plug-in -->
<!-- Questa parte dovrebbe essere contenuta in un plug-in di documentazione -->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(nel file infoset.xml)
<!-- Definire l'infoset e tutte le relative visualizzazioni. -->
<infoset id="ex1InfosetId" label="%help_system_example">
<infoview id="topicsView" label="%topics"/>
</infoset>
(nel file infosetTopics.xml)
<!-- Definire adesso un argomento "contenitore" degli argomenti generali. In questo modo -->
<!-- tutti questi argomenti generali possono essere inseriti più rapidamente nella visualizzazione dell' -->
<!--Infoset. -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topic id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
Definire gli argomenti contenuti negli argomenti generali sopra riportati:
(nel file topics.xml)
<topics id="topics">
<topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
<topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
</topic>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>
Definire adesso le azioni di inserimento necessarie per creare la gerarchia della documentazione:
(nel file infosetActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(nel file topicsActions.xml)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">Nell'immagine viene illustrata la gerarchia di documentazione che viene visualizzata nel workbench di Eclipse:
<insert from="org.eclipse.help.examples.ex1.aConceptId"
to="org.eclipse.help.examples.ex1.concepts" as="child"/><insert from="org.eclipse.help.examples.ex1.aTaskId"
to="org.eclipse.help.examples.ex1.tasks" as="child"/><insert from="org.eclipse.help.examples.ex1.aReferenceId"
to="org.eclipse.help.examples.ex1.references" as="child"/><insert from="org.eclipse.help.examples.ex1.aSampleId"
to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
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'opzionale implementazione predefinita dell'interfaccia utente del sistema della guida, in dotazione con la piattaforma Eclipse, supporta completamente il punto di estensione contributions.