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"/>
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.
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ä.
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.