Ohjepalvelin ja tiedostosijainnit

Ympäristössä on oma dokumentaatiopalvelin, joka tarjoaa lisäosan dokumentaation Web-sivut. Mukautetun palvelimen avulla ympäristö voi käsitellä HTML-sisältöä selaimessa itsenäisesti ja tarjota lisäosat huomioon ottavan tuen. Suurin ero lisäosien kehittäjille on, että käytettävissä on hieman enemmän joustavuutta sen suhteen, kuinka tiedostot jäsennetään ja linkit määritetään.

Dokumentaatiolisäosa voidaan ajaa jar-tiedostosta tai purkaa lisäosahakemistoon asennuksen aikana. Lisäosan jar-arkistotiedostoa ei laajenneta lisäosahakemistoon, kun plugin-elementin unpack-määritteen arvoksi on määritetty true -tuoteominaisuuden manifest-tiedostossa. Tällaisessa lisäosassa dokumentaatio on tiivistetty lisäosan jar-tiedostoon yhdessä muiden lisäosatiedostojen kanssa.

Purettuina ajettavissa lisäosissa dokumentaatio voidaan toimittaa zip-tiedostossa, jolloin vältetään ongelmat, joita voi aiheutua, kun lisäosahakemistossa on suuri määrä tiedostoja. Esimerkkilisäosassa luotiin alihakemisto nimeltä html.  Vaihtoehtoisesti html-tiedostot olisi voitu sijoittaa zip-tiedostoon nimeltä doc.zip. Tämän zip-tiedoston on jäljiteltävä lisäosahakemiston tiedostorakennetta. Tässä tapauksessa sen on sisällettävä alihakemisto html ja kaikki html-hakemiston alla oleva sisältö.

Huomaa, että jar-tiedostosta ajettavissa lisäosissa ei tarvitse olla doc.zip-tiedostossa olevaa dokumentaatiota. Ohjejärjestelmä ei tue tällaista doc.zip-tiedoston käyttöä purkamattoman lisäosan jar-tiedoston yhteydessä.

Kun pakkaamattomana ajettavan lisäosan tiedostonimiä tulkitaan, ohjepalvelin etsii asiakirjoja doc.zip-tiedostosta, ennen kuin se etsii niitä lisäosahakemistosta itsestään. Kun sitä käytetään linkkinä, href-tunnisteen argumentin oletetaan viittaavan nykyiseen lisäosaan. Tarkastellaan seuraavaa linkkiä:

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

Ohjelisäosa etsii tätä tiedostoa seuraavasti:

Tarkan linkin avulla voidaan viitata mihin tahansa Web-sisältöön. 

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

Kansallinen kieli ja käännetty dokumentaatio

Ympäristön ohjejärjestelmä käyttää samaa kansallisen kielen hakemiston hakua kuin muukin ympäristö etsiessään käännettyjä tiedostoja. (Hakemistorakenteen kuvaus on kohdassa Paikallistunnuskohtaiset tiedostot.) Jos käytät doc.zip-tiedostoa, tee doc.zip-tiedosto kutakin paikallistunnusta kohden ja sijoita se oikeaan paikallistunnushakemistoon. (Älä toisinna nl-paikallistunnushakemistorakennetta doc.zip-tiedostossa.)

Paikallistunnuskohtaisten hakemistojen lisäksi ohjejärjestelmä tarkistaa ikkunointijärjestelmän ja käyttöjärjestelmän hakemistot, kun se etsii ohjeresursseja. Haku toteutetaan seuraavassa järjestyksessä: ws-, os- ja nl-alihakemistot, sitten lisäosan juurihakemisto, kunnes resurssi löytyy. Asiakirjat ja muut resurssit kuten kuvat, jotka eroavat eri järjestelmien välillä, tulee sijoittaa ws- tai os-hakemistoihin tiettyä ympäristöä varten.

Lisäosien ristiviittaus

Href-argumentti voi viitata myös toisen lisäosan sisältöön. Tämä tehdään käyttämällä erityistä lisäosien ristiviittausmerkintää, jonka ohjepalvelin tulkitsee:

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

Tässä PLUGINS_ROOT tulkitaan ajonaikaisesti ja korvataan lisäosien juurihakemistolla. Voit määrittää oman lisäosan tunnuksen kohtaan another_plugin_id. Voit esimerkiksi linkittää ohjelmointioppaan tämän luvun seuraavaan ohjeaiheeseen:

   <topic label="Ympäristön dokumentaation ohjeluku" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>

Ennen versiota 3.2 viittaukset muiden lisäosien sisältämiin asiakirjoihin tehtiin käyttämällä kahta pistettä ('..'), joilla siirryttiin lisäosan tasolle, minkä jälkeen viitattiin lisäosan tunnukseen, jota seurasi HREF-linkki lisäosan sisältämään ohjeaiheeseen. Nykyinen suositeltava käytäntö on käyttää PLUGINS_ROOT-määritettä merkkien '..' sijaan. Kyseisen muuttujan käytöllä vältetään ylä- ja alatason välillä liikkuminen viittauksissa. Lisäksi muuttujaa voi käyttää kaikkien ohjeresurssien (kuvien, linkkien, CSS-tiedostojen, java-komentosarjatiedostojen jne.) URL-osoitteiden yhteydessä.

Huomautus: Kun viittaat sisältöön toisesta lisäosasta, varmista, että käytät lisäosan tunnusta (id) siinä muodossa kuin se on esitelty sen plugin.xml-tiedostossa, ei hakemiston nimeä. Vaikka ne ovat monesti samat, on tärkeää tarkistaa, että käytät tunnusta etkä hakemiston nimeä.

Tuotelisäosaan viittaaminen.

Tuotteistustiedot sijoitetaan usein lisäosaan, joka määrittää tuotteen kuten kohdassa Tuotteen määritys on kuvattu. Tuotteen lisäosan ohjeresursseihin voi viitata sisällysluettelosta tai ohjeaiheista käyttämällä lisäosan tunnuksessa erikoistunnistetta PRODUCT_PLUGIN. Esimerkki:

   href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"

viittaa tyylitiedostoon, joka sijaitsee ajossa olevan tuotteen lisäosassa.