Server della Guida e percorsi dei file

La piattaforma utilizza il proprio server della documentazione per fornire le pagine web reali per la documentazione del plugin.  Un server personalizzato consente alla piattaforma di gestire il contenuto HTML in modo indipendente dal browser e di fornire un supporto di plugin effettivo.  La differenza principale tra l'utente e uno sviluppatore di plugin consiste nel fatto che l'utente dispone di una maggiore flessibilità nel modo di strutturare i file e di specificare i collegamenti.

Un plugin di documentazione può essere eseguito da un file jar oppure decompresso nella directory dei plugin durante l'installazione. Un jar di archivio dei plugin non viene espanso in una directory di plugin quando il valore dell'attributo unpack dell'elemento plugin viene specificato come true nella funzione manifest. In tale plugin, la documentazione viene compressa nel jar del plugin, insieme agli altri file di plugin.

Nei plugin che sono eseguiti senza decompressione, la documentazione può essere distribuita in un file zip, evitando così i problemi che possono verificarsi quando il numero di file presenti in una directory di plugin è particolarmente elevato. Nel plugin di esempio, è stata creata una sottodirectory denominata html.  In alternativa, sarebbe stato possibile inserire i file html in un file zip denominato doc.zip.  Tale file zip deve ricreare la struttura file presente nella directory dei plugin.  Nel nostro caso, deve contenere la sottodirectory html e tutto il contenuto di html.

Si noti che per i plugin che sono eseguiti da un file jar, non è necessario che la documentazione sia contenuta anche nel file doc.zip e l'impostazione del file doc.zip in un jar di plugin non espanso non è supportata dal sistema della guida.

Quando risolve i nomi file in un plugin che viene eseguito senza decompressione, il server della guida ricerca i documenti nel file doc.zip prima di ricercarli nella stessa directory dei plugin.  Quando è utilizzato come collegamento, l'argomento in un href viene interpretato come relativo al plugin corrente.  Si consideri il collegamento che segue:

   <topic label="Ref1" href="html/ref/ref1.html"/>

Il plugin della Guida ricercherà il file in questione nel modo indicato di seguito:

Un collegamento completo può essere utilizzato per fare riferimento a qualsiasi contenuto presente sul Web. 

   <topic label="Ref1" href="http://www.example.com/myReference.html"/>

Lingua nazionale e documentazione tradotta

Il sistema della Guida della piattaforma utilizza lo stesso schema di ricerca della directory delle lingue nazionali impiegato dal resto della piattaforma per l'individuazione dei file tradotti.  (Vedere File specifici delle impostazioni internazionali per maggiori dettagli su questa struttura di directory).  Se si sta utilizzando un file doc.zip, è necessario generare un file doc.zip per ciascun gruppo di impostazioni internazionali e inserirlo nella directory delle impostazioni internazionali corretta.  (Non replicare la struttura della directory delle impostazioni internazionali nl nel file doc.zip).

Oltre alle directory specifiche della locale, il sistema della guida verifica le directory del sistema operativo e del sistema a finestre quando ricerca le risorse della guida. La ricerca viene eseguita nel seguente ordine: le sottodirectory ws, os, nl, poi la directory principale del plugin, fino a quando non viene individuata la risorsa. I documenti e le altre risorse, quali immagini che possono essere diverse tra i sistemi, dovrebbero essere collocate nelle directory ws o os per le specifiche piattaforme.

Riferimenti plugin incrociati

L'argomento href può fare riferimento anche al contenuto di un altro plugin.  Se si desidera effettuare questa operazione, occorre utilizzare una speciale notazione di riferimenti plugin incrociati che viene risolta dal server della Guida:

   <topic label="Ref1" href="../"another_plugin_id"/ref/ref1.html"/>

Ad esempio, è possibile creare un collegamento a questo capitolo della guida alla programmazione mediante il seguente argomento:

   <topic label="Help Chapter in Platform Doc" href="../org.eclipse.platform.doc.isv/guide/help.html"/>

Note:  quando si fa riferimento al contenuto di un altro plugin, assicurarsi di utilizzare l'id del plugin, come dichiarato nel relativo file plugin.xml , non il nome della directory.  Sebbene spesso coincidano, è importante verificare che si sta utilizzando l'ID e non il nome della directory.

Riferimenti al plugin del prodotto.

Le informazioni di personalizzazione si trovano spesso in un plugin che definisce un prodotto come illustrato in Definizione di un prodotto. I riferimenti alle risorse della guida nel plugin del prodotto si possono trovare nel sommario o in argomenti che utilizzano un identificativo speciale "PRODUCT_PLUGIN" per l'ID del plugin. Ad esempio,

   href="../PRODUCT_PLUGIN/book.css"

fa riferimento ad un foglio di stile che si trova nel plugin del prodotto attualmente in esecuzione.