Plattformen utnyttjar sin egen dokumentationsserver till att tillhandahålla de faktiska webbsidorna för dokumentationen till ditt insticksprogram. En anpassad server gör att plattformen kan hantera HTML-innehåll oavhängigt av webbläsaren, samt att tillhandahålla funktioner som beror på insticksprogrammet. Huvudskillnaden för dig som utvecklare av insticksprogram är att du får något större flexibilitet i hur du strukturerar dina filer och skapar dina länkar.
Ett insticksprogram för dokumentation kan köras från en jar-fil eller packas upp i katalogen för insticksprogrammet vid
installation. Ett insticksprogram med en jar-arkivfil expanderas inte till en katalog för insticksprogram när värdet för
attributet unpack
i elementet plugin
får värdet sant i funktionsmanifestet . I ett sånt insticksprogram komprimeras dokumentationen i insticksprogrammets jar, tillsammans med andra insticksfiler.
I insticksprogram som körs ouppackade kan dokumentationen levereras i en zip-fil, vilket gör att man undviker problem som kan bli resultatet när ett stort antal filer finns närvarande i katalogen för ett insticksprogram. I vårt exempel på insticksprogram har vi skapat en underkatalog som heter html. Alternativt hade vi kunnat lägga våra html-filer i en zip-fil med namnet doc.zip. Den zip-filen måste efterlikna filstrukturen under insticksprogrammets katalog. I vårt fall måste den innehålla underkatalogen html och allt innehåll under html.
Observera att med insticksprogram som körs från en jar, behöver dokumentationen inte dessutom ligga i en doc.zip, och att konfigurera doc.zip i en oexpanderad insticks-jar är en funktion som inte finns i hjälpsystemet
När filnamn tolkas i ett insticksprogram som körs ouppackat, söker hjälpservern i filen doc.zip efter dokument innan den söker i insticksprogrammets katalog. När det används som länk antas argumentet i en href relatera till det aktuella insticksprogrammet. Studera följande länk:
<topic label="Ref1" href="html/ref/ref1.html"/>
Insticksprogrammet för hjälp kommer att söka efter den filen på följande sätt:
En korrekt definierad länk kan användas till att hänvisa till vilket innehåll som helst på webben.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
Plattformens hjälpsystem utnyttjar samma söksystem för språkkataloger som används i resten av plattformen för att söka efter översatta filer. (Se Språkmiljöspecifika filer om du vill ha en förklaring till den här katalogstrukturer.) Om du använder en doc.zip-fil, bör du skapa en doc.zip-fil för varje språkmiljö och lägga den i rätt språkmiljökatalog. (Du bör inte replikera katalogstrukturen för språkmiljö nl inuti doc.zip-filen.)
Förutom de språkmiljöspecifika katalogerna kontrollerar hjälpsystemet fönster- och operativsystemets kataloger när det söker efter hjälpresurser. Sökning genomförs i följande ordning: underkatalogerna ws, os, nl, sedan insticksprogrammets rot, ända tills resursen har hittats. Dokument och andra resurser som bilder som skiljer sig åt mellan system bör placeras i katalogerna ws eller os under respektive plattform.
Argumentet href kan även hänvisa till innehåll från ett annat insticksprogram. Det görs med en särskild korsrefererande not för insticksprogram som tolkas av hjälpservern:
<topic label="Ref1" href="PLUGINS_ROOT/another_plugin_id/ref/ref1.html"/>
Här löses PLUGINS_ROOT
under körning och ersätts med rotkatalogen för insticksprogrammen. Du kan ange ditt eget insticksprograms-ID för another_plugin_id
. Till exempel skulle du kunna länka till det här kapitlet i programmerarhandboken med
följande avsnitt:
<topic label="Hjälpkapitel i plattformsdokument" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
Före 3.2 gjordes referenser till dokument i andra insticksprogram med hjälp av '..'
som användes till att gå upp till insticksprogramsnivån och sedan angavs en referens till insticksprograms-ID:t, följt HREF till avsnittet i insticksprogrammet. Det rekommenderade sättet är nu att använda PLUGINS_ROOT
i stället för '..'. Om du använder den här variabeln undviker du bläddringar upp och ned bland referenser. Den kan användas för alla resurs-URL-adresser i hjälpdokumenten (bilder, länkar, CSS-filer, Java-skriptfiler osv.).
Obs! När du refererar till innehåll från ett annat insticksprogram ska du se till att använda insticksprogrammets ID, som det är deklarerat i plugin.xml-filen som hör till den, inte katalognamnet. De är visserligen ofta desamma i praktiken, men det är viktigt att kontrollera att du använder IDt, och inte katalognamnet.
Märkesinformation läggs ofta in i ett insticksprogram som definierar en produkt
såsom förklaras i Definiera en produkt. Det går att referera till hjälpresurser
i produktens insticksprogram från innehållsförteckningen och
från avsnitt genom att använda special-ID:t PRODUCT_PLUGIN
för insticksprograms-ID:t. Exempel:
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
refererar till en formatmall i insticksprogrammet för produkten som körs nu.