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