Platformen benytter sin egen dokumentationsserver til at levere websiderne til brug for plugin'ens dokumentation. En tilpasset server giver platformen tilladelse til at håndtere HTML-indholdet på browseruafhængig vis og til at stille plugin-relevant understøttelse til rådighed. Den største forskel for dig som plugin-udvikler er, at du har lidt mere fleksibilitet i den måde, du strukturerer filer og angiver link på.
En dokumentations-plugin kan udføres fra en jar-fil eller udpakkes i et plugin-bibliotek under installationen. En plugin-arkiv-jarfil udvides ikke i et plugin-bibliotek, hvis værdien af attributten unpack
for plugin
-elementet er angivet til sandt i funktionsmanifestet. I en sådan plugin er dokumentationen komprimeret i plugin'ens jar-fil sammen med andre plugin-filer.
I plugins, der udføres udpakket, kan dokumentationen stilles til rådighed i en zip-fil. Derved undgås eventuelle problemer, der kunne opstå ved et stort antal filer i et plugin-bibliotek. I plugin-eksemplet blev der oprettet et underbibliotek med navnet html. Alternativt kan html-filerne placeres i en zip-fil med navnet doc.zip. Denne zip-fil skal efterligne den filstruktur, der ligger under plugin-biblioteket. I dette tilfælde skal det indeholde underbiblioteket html og alt, hvad der ellers ligger under html.
Bemærk, at for plugins, der udføres fra en jar-fil, er der ikke brug for, at dokumentationen også er indeholdt i doc.zip, og at en sådan opsætning af doc.zip i en ikke-udpakket plugin-jar-fil ikke understøttes af hjælpen.
Ved opløsning af filnavnene i en plugin, der udføres udpakket, søger hjælpeserveren i filen doc.zip, inden den søger i selve plugin-biblioteket. Når den benyttes som et link, antages argumentet i en href at være relativt til den aktuelle plugin. Se på følgende link:
<topic label="Ref1" href="html/ref/ref1.html"/>
Hjælpe-plugin'en søger efter filen på følgende måde:
Et fuldt kvalificeret link kan bruges til at referere til indhold på webben.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
Platformens hjælp bruger det samme biblioteksopslagsskema for nationalt sprog, som benyttes af resten af platformen til at finde oversatte filer. (I Sprogspecifikke filer er denne biblioteksstruktur forklaret.) Hvis du bruger en doc.zip-fil, skal du producere en doc.zip-fil for hvert sprog og placere den i det relevante sprogbibliotek. (Du skal ikke replikere nl-sprogbiblioteksstrukturen i doc.zip-filen.)
Foruden sprogspecifikke biblioteker kontrollerer hjælpen vinduessystemets og styresystemets biblioteker, når der søges efter hjælperessourcer. Opslag foretages i følgende rækkefølge: ws-, os-, nl-underbiblioteker og derefter plugin-roden, indtil ressourcen er fundet. Dokumenter og andre ressourcer, f.eks. billeder, som er forskellige fra system til system, bør placeres i ws- eller os-biblioteker for specifikke platforme.
Argumentet href kan også referere til indhold fra en anden plugin. Dette sker ved, at der benyttes en særlig notation til plugin-krydsreference, der opløses af hjælpeserveren.
<topic label="Ref1" href="PLUGINS_ROOT/en_anden_plugin_id/ref/ref1.html"/>
Her opløses PLUGINS_ROOT
ved runtime og erstattes med rodbiblioteket for plugin'en.
Du kan angive din egen plugin-id for
en_anden_plugin_id
. Du kunne f.eks. oprette linke til dette kapitel i programmørguiden vha. 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 blev referencer til dokumenter i andre plugins oprettet vha. '..' for at gå op til plugin-niveauet, derefter blev der henvist til plugin-id'en efterfulgt af en HREF til emnet i plugin'en. Den anbefalede måde at gøre det på nu er at bruge PLUGINS_ROOT
i stedet for '..'. Ved at bruge denne variabel undgår du at skulle gå op og ned, og metoden kan bruges til alle ressource-URL'er i hjælpedokumenter - billeder, link, CCS-filer, Java-scriptfiler osv.
Bemærk: Når du refererer til indhold fra en anden plugin, skal du sikre dig, at du bruger plugin'ens id, som den er erklæret i dens plugin.xml-fil, og ikke dens biblioteksnavn. Selvom disse som regel er ens, er det vigtigt at kontrollere, at du bruger id'en og ikke biblioteksnavnet.
Varemærkeoplysninger er ofte placeret i en plugin, der definerer et produkt, hvilket er beskrevet i Definér produkt. Der kan refereres til hjælperessourcerne i produkt-plugin'en fra indholdsfortegnelsen eller emnerne vha. en særlig id PRODUCT_PLUGIN
for plugin-id'en. For eksempel
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
refererer til en egenskabsark, der er placeret i plugin'en for det produkt, der aktuelt udføres.