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.

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

Quando risolve i nomi file, 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:

Dal release 3.0, l'intero plugin può essere installato in un formato compresso ed eseguito direttamente da un jar. Un jar di installazione dei plugin non viene esteso 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. 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 esteso non è supportata dal sistema della guida.

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).

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.

 

Informazioni particolari.