Installazione del sistema autonomo della guida

È possibile utilizzare il sistema della Guida di Eclipse anche se si sta creando un'applicazione che non si basa sulla struttura di Eclipse. L'applicazione può creare pacchetti e installare il sistema autonomo della Guida, una versione molto ridotta di Eclipse che dispone di tutti i componenti tranne il sistema della Guida. Quindi l'applicazione può effettuare chiamate API dal menu Guida o dagli oggetti di interfaccia utente e avviare il browser della Guida. Il sistema autonomo della Guida dispone di tutte le funzioni del sistema della Guida integrata, eccetto la guida a comparsa e la guida attiva. Quando un'applicazione non è basata su Java, oppure se è necessaria la guida quando l'applicazione non è in esecuzione, è possibile utilizzare una guida autonoma da una shell di sistema, uno script shell oppure un collegamento al desktop, e fornire le opzioni della riga comandi invece di richiamare le API Java.

Il sistema di guida autonomo consente di trasmettere le opzioni richieste per personalizzare vari aspetti del sistema della guida. Sono supportate le seguenti opzioni:

Installazione/creazione pacchetti

Questa procedura è destinata all'esperto di integrazione del sistema della Guida e non prevede di ricoprire tutti i possibili scenari. Si presuppone che tutta la documentazione venga distribuita come plug-in di Eclipse e che, generalmente, si abbia familiarità con il sistema della Guida di Eclipse.
  1. Scaricare il driver binario di run-time della piattaforma Eclipse da www.eclipse.org.
  2. Installare (decomprimere) il driver nella directory dell'applicazione, ad esempio, d:\myApp. Verrà creata in tal modo una sottodirectory di Eclipse, d:\myApp\eclipse, contenente il codice richiesto per la piattaforma Eclipse (che include il sistema della Guida).

Modalità di richiamo delle classi Help da Java

  1. Accertarsi che d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.jar si trovi nel percorso classi dell'applicazione. La classe utilizzata per avviare, aprire e chiudere il sistema della Guida è org.eclipse.help.standalone.Help.
  2. Creare una matrice di String che contenga le opzioni da trasmettere al sistema della guida. Di solito, l'opzione eclipsehome è obbligatoria.
    String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" }; 
  3. Creare, nella propria applicazione, un'istanza della classe Help alla quale trasmettere le opzioni. È consigliabile mantenere questo oggetto fino al termine dell'applicazione.
    Help helpSystem = new Help(options); 
  4. Per avviare il sistema della Guida:
    helpSystem.start(); 

  5. Per richiamare la Guida all'occorrenza:
    helpSystem.displayHelp(); 

    È inoltre possibile richiamare la Guida relativamente a specifici file TOC o argomenti principali:

    helpSystem.displayHelp("/com.mycompany.mytool.doc/toc.xml");
    helpSystem.displayHelp("/com.mycompany.mytool.doc/tasks/task1.htm");
  6. Per avviare la Guida sensibile al contesto richiamare helpSystem.displayContext(contextId, x, y), dove contextId corrisponde a un id contesto completo. Le coordinate dello schermo, x e y,non vengono correntemente utilizzate.
  7. Al termine dell'applicazione, per la chiusura del sistema della Guida:

    helpSystem.shutdown(); 

Modalità di richiamo della guida da riga comandi

La classe org.eclipse.help.standalone.Help dispone di un metodo principale che può essere utilizzato per avviare una guida autonoma da riga comandi. La sintassi per la riga comandi è:

-command start | shutdown | (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-host helpServerHost] [-port helpServerPort] [-servertimeout timeout] [platform options] [-vmargs JavaVMarguments]

Un modo semplice per visualizzare la guida è utilizzare il comando

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.jar org.eclipse.help.standalone.Help -command displayHelp

dalla directory d:\myApp\eclipse. Per visualizzare file TOC o argomenti specifici utilizzare

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.jar org.eclipse.help.standalone.Help -command displayHelp /com.mycompany.mytool.doc/tasks/task1.htm

In questo caso il sistema della guida verrà avviato, effettuerà la visualizzazione e resterà attivo per consentire all'utente di continuare a consultare la guida dopo l'esecuzione del comando. Per controllare la durata dell'esecuzione del sistema di guida, utilizzare i comandi start e shutdown, con il comando displayHelp. Ad esempio, utilizzare il comando

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.jar org.eclipse.help.standalone.Help -command start

[Facoltativo] Installazione di un insieme minimo di plug-in

La guida autonoma non richiede l'intero pacchetto della piattaforma  Eclipse. La guida autonoma può essere eseguita con i seguenti plug-in (presenti nella directory   eclipse\plugins):

org.apache.lucene
org.apache.xerces
org.eclipse.core.boot
org.eclipse.core.resources
org.eclipse.core.runtime
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.update.core

In funzione del sistema operativo o dell'architettura della macchina, oltre a questi plug-in può essere necessario installare anche i corrispondenti frammenti dei plug-in indicati in precedenza (se esistono). Ad esempio, su Windows, è necessario aggiungere i seguenti frammenti (presenti sempre nella directory eclipse\plugins):

org.eclipse.core.resources.win32
org.eclipse.update.core.win32

Su Windows, è possibile fornire un browser della guida diverso (un browser web Internet Explorer con SWT incorporato) aggiungendo i seguenti plug-in e frammenti alla configurazione minima:

org.eclipse.help.ui.win32
org.eclipse.help.ui
org.eclipse.jface.text
org.eclipse.jface
org.eclipse.search
org.eclipse.swt.win32
org.eclipse.swt
org.eclipse.text
org.eclipse.ui.editors
org.eclipse.ui.views
org.eclipse.ui.win32_2.1.0 org.eclipse.ui.workbench.texteditor
org.eclipse.ui.workbench
org.eclipse.ui

Copyright IBM Corporation e altri 2000, 2003.