Hjelpeserver og filplasseringer

Plattformen bruker sin egen dokumentasjonsserver til å oppgi web-sidene for plugin-modulens dokumentasjon. Ved hjelp av en tilpasset server kan plattformen håndtere HTML-innhold for alle typer nettlesere og gi plugin-støtte. Den største forskjellen for deg som plugin-utvikler, er at du har noe mer fleksibilitet til å strukturere filene og oppgi linker.

En plugin-modul for dokumentasjon kan kjøres fra en jar-fil eller upakket i en plugin-katalog under installeringen. Et jar-arkiv for plugin-modulen utvides ikke til en plugin-katalog når verdien for attributtet unpack i plugin-elementet er satt til "true" i funksjonsmanifestet. I slike plugin-moduler komprimeres dokumentasjonen i plugin-modulens jar-fil sammen med andre filer for plugin-modulen.

I plugin-moduler som kjøres upakket, kan dokumentasjonen leveres i en zip-fil for å unngå problemer når plugin-katalogen innehoder mange filer. I vårt eksempel på plugin-modul opprettet vi underkatalogen html.  Vi kunne også lagt html-filen i en zip-fil med navnet doc.zip. En slik zip-fil må gjenspeile den underliggende filstrukturen for plugin-katalogen. I vårt eksempel må den inneholde underkatalogen html og alt innhold i html.

Merk at hvis plugin-modulene kjøres fra en jar, er det ikke behov for at ytterligere dokumentasjon skal legges i doc.zip, og hjelpesystemet støtter ikke et slikt oppsett av doc.zip i en plugin-jar som ikke er utpakket.

Når hjelpeserveren behandler filnavn i en plugin-modul som kjøres upakket, søker den etter dokumenter i filen doc.zip før den søker gjennom selve plugin-katalogen.  Når det brukes linker, forutsettes det at argumentet i href er relativt til den gjeldende plugin-modulen. Se på følgende link:

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

Plugin-modulen for hjelp søker etter filen på følgende måte:

Det kan brukes en fullstendig link til å referere til innhold på nettet. 

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

Nasjonalspråk og oversatt dokumentasjon

Plattformens hjelpesystem finner oversatte filer ved å søke etter språkkatalog på samme måte som det gjøres i plattformen forøvrig.  (Du finner en forklaring på denne katalogstrukturen i Språkspesifikke filer.) Hvis du bruker en fil som doc.zip, må du lage en doc.zip for hvert språkmiljø og plassere den i riktig språkmiljøkatalog. (Du må ikke replikere strukturen i språkmiljøkatalogen nl i filen doc.zip.)

I tillegg til kataloger som er spesifikke for språkmiljø, kontrollerer hjelpesystemet kataloger for vindussystemet og operativsystemet ved lokalisering av hjelperessurser. Søkingen utføres i følgende rekkefølge: først underkatalogene ws, os og nl, deretter søkes det gjennom roten for plugin-modulen til ressursen blir funnet. Dokumenter og øvrige ressurser, for eksempel bilder som er ulike fra system til system, må plasseres under ws- eller os-katalogen for spesifikk plattform.

Referanser på tvers av plugin-moduler

Argumentet href kan også referere til innhold fra en annen plugin-modul.  Dette gjøres ved å bruke en bestemt notasjon for referanser på tvers av plugin-moduler. Dette blir behandlet av hjelpeserveren.

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

PLUGINS_ROOT blir behandlet under kjøring, og erstattet med plugin-modulenes rotkatalog. Du kan oppgi en egen plugin-ID for another_plugin_id. Du kan for eksempel opprette en link til dette kapittelet i programmeringshåndboken med følgende emne:

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

Før 3.2 ble det referert til dokumenter i andre plugin-moduler ved å bruke '..' for å gå opp i plugin-nivået, deretter ble det referert til plugin-IDen fulgt av HREF til emnet i plugin-modulen. Den anbefalte måten å gjøre dette på, er å bruke PLUGINS_ROOT i stedet for '..'. Når du bruker denne variabelen, unngår du disse opp/ned-turene i referansene. Variabelen kan brukes til alle ressurs-URLene i hjelpedokumentene (bilder, linker, CSS-filer, java-skriptfiler etc.)

Merk:  Når du refererer til innhold fra en annen plugin-modul, må du bruke IDen for plugin-modulen slik den er deklarert i filen plugin.xml, og ikke katalognavnet. I praksis er disse ofte identiske, men det er viktig å kontrollere at du bruker IDen og ikke katalognavnet.

Referanse til plugin-modul for produktet

Merkevareinformasjon er ofte plassert i en plugin-modul som definerer et produkt, som beskrevet i Definere et produkt. Det kan refereres til hjelperessurser i produktets plugin-modul fra innholdsfortegnelsen eller emnene ved hjelp av en spesiell ID, PRODUCT_PLUGIN, for plugin-IDen. I eksempelet nedenfor,

   href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"

refereres det til et stilark i plugin-modulen for produktet som kjøres nå.