Help-server en bestandslocaties

Het platform maakt gebruik van een eigen documentatieserver om de werkelijke webpagina's voor uw plugindocumentatie aan te leveren. Door een aangepaste server te gebruiken, kan HTML-content onafhankelijk van een browser worden afgehandeld en ondersteuning voor plugins worden geboden. Het grootste verschil voor u als pluginontwikkelaar is dat u meer mogelijkheden hebt om bestanden te structureren en links op te geven.

Een documentatieplugin kan worden uitgevoerd vanuit een JAR-bestand of worden uitgepakt in een plugindirectory tijdens de installatie. Een JAR-pluginbestand wordt niet uitgepakt in een plugindirectory als de opgegeven waarde voor het kenmerk unpack van het element plugin in het featuremanifest 'true' is. Bij een dergelijke plugin wordt de documentatie samen met andere pluginbestanden gecomprimeerd in het JAR-bestand van de plugin.

Bij plugins die niet-gecomprimeerd worden uitgevoerd kan de documentatie worden aangeleverd in een ZIP-bestand. Zo vermijdt u eventuele problemen die het gevolg zijn van een (te) groot aantal bestanden in een plugindirectory. In onze voorbeeldplugin hebben we een subdirectory met de naam html gemaakt. We hadden onze HTML-bestanden ook kunnen opslaan in een ZIP-bestand met de naam doc.zip. Dit ZIP-bestand moet dan de bestandsstructuur onder de plugindirectory nabootsen. In dit geval moet het de subdirectory html en alle inhoud van html bevatten.

Voor plugins die worden uitgevoerd vanuit een JAR-bestand hoeven geen aanvullende documentatiegegevens te worden opgenomen in doc.zip, en wordt een dergelijke configuratie van doc.zip in een niet-uitgepakt JAR-pluginbestand niet in het Help-systeem ondersteund.

Bij het omzetten van bestandsnamen in een plugin die niet-gecomprimeerd wordt uitgevoerd, wordt door de Help-server eerst naar documenten gezocht in het bestand doc.zip, en daarna pas in de plugindirectory. Bij gebruik als link wordt het argument in een href beschouwd als een relatief pad ten opzichte van de huidige plugin. Bekijk de volgende link:

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

Hierbij wordt door de Help-plugin als volgt naar dit bestand gezocht:

U kunt een volledig gekwalificeerde link gebruiken om te verwijzen naar willekeurige content op internet. 

   <topic label="Ref1" href="http://www.voorbeeld.com/mijnNaslag.html"/>

Taal en vertaalde documentatie

Voor het opzoeken van vertaalde bestanden wordt in het Help-systeem van het platform hetzelfde taal- en landinstellingenschema gebruikt als in de rest van het platform. (Zie Locale-specifieke bestanden voor nadere informatie over deze directorystructuur.) Als u een bestand doc.zip wilt gebruiken, moet u voor elke locale een bestand doc.zip aanleveren en dit in de juiste directory van de locale plaatsen. (U dient de directorystructuur van de locale nl niet te repliceren in het bestand doc.zip.)

Naast locale-specifieke directory's wordt door het Help-systeem ook in directory's van het venstersysteem (ws) en het besturingssysteem (os) naar Help-resources gezocht. Er wordt achtereenvolgens gezocht in de subdirectory's ws, os, nl en de hoofdmap van de plugin totdat de resource is gevonden. Documenten en andere resources, zoals afbeeldingen die per systeem kunnen verschillen, moeten voor een specifiek platform in de directory ws of os worden geplaatst.

Verwijzingen naar andere plugins

Met het argument href kan ook worden verwezen naar content in een andere plugin. Hiertoe gebruikt u een speciale notatie die door de Help-server kan worden omgezet:

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

Hierbij wordt PLUGINS_ROOT ten tijde van de verwerking opgelost en vervangen door de hoofddirectory voor de plugins. Voor another_plugin_id kunt u uw eigen plugin-ID opgeven. U kunt bijvoorbeeld met het volgende onderwerp een link naar dit hoofdstuk van de handleiding voor programmeurs maken:

   <topic label="Help-hoofdstuk in platformdocumentatie" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>

Vóór 3.2 werden verwijzingen naar documenten in andere plugins gedefinieerd met '..' om omhoog te gaan naar het pluginniveau, gevolgd door een verwijzing naar het plugin-ID en de HREF naar het onderwerp in de plugin. De aanbevolen methode om dit te doen is nu PLUGINS_ROOT te gebruiken in plaats van '..'. Met deze variabele vermijdt u het niveaus omhoog/omlaag gaan in verwijzingen. Bovendien kan deze variabele worden gebruikt voor alle URL's van resources in Help-documenten (afbeeldingen, links, CSS-bestanden, Java-scripts, enzovoort).

Opmerking: wanneer u verwijst naar content van een andere plugin, moet u wel het id van de plugin gebruiken dat is gedeclareerd in het bijbehorende bestand plugin.xml, en niet de directorynaam. Hoewel deze in de praktijk vaak hetzelfde zijn, dient u zich ervan te vergewissen dat u het ID gebruikt en niet de directorynaam.

Verwijzingen naar de productplugin

Vaak worden productgegevens in een productplugin geplaatst (zie Een product definiëren voor meer informatie). U kunt verwijzingen naar Help-resources in de productplugin opnemen in de inhoudsopgave of de lijst met onderwerpen met de speciale identificatie PRODUCT_PLUGIN voor het plugin-ID. Een voorbeeld:

   href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"

verwijst naar een stijlblad in de plugin voor het product dat wordt uitgevoerd.