Aby udostępnić rzeczywiste strony WWW dokumentacji wtyczki, platforma korzysta z własnego serwera dokumentacji. Własny serwer umożliwia platformie obsługę treści plików HTML w sposób niezależny od przeglądarki oraz obsługę współpracy z wtyczkami. Podstawową różnicą dla programisty jest zwiększona elastyczność w sposobie ustalania struktury plików i określania odsyłaczy.
Wtyczkę dokumentacji można uruchamiać z pliku JAR lub można go rozpakować
podczas instalacji do katalogu wtyczek. Plik JAR archiwum wtyczki
nie jest rozpakowywany do katalogu wtyczek, jeśli atrybut unpack
elementu
plugin
w manifeście składnika ma wartość true.
W takiej wtyczce dokumentacja jest skompresowana w pliku JAR razem z innymi plikami wtyczki.
We wtyczkach, które są uruchamiane w postaci rozpakowanej, dokumentacja może być dostarczona w pliku ZIP, co pozwala uniknąć problemów wynikających z dużej liczby plików w katalogu wtyczki. W przykładowej wtyczce utworzono podkatalog nazwany html. Równie dobrze pliki html mogłyby się znajdować w pliku ZIP nazwanym doc.zip. Ten plik ZIP musi imitować strukturę plików katalogu wtyczki. W tym przypadku musi zawierać podkatalog html wraz z całą jego treścią.
W przypadku wtyczek uruchamianych z pliku JAR nie ma potrzeby, aby dokumentacja była dodatkowo przechowywana w pliku doc.zip, a konfigurowanie pliku doc.zip w nierozpakowanym pliku JAR wtyczki nie jest obsługiwane przez system pomocy.
W trakcie interpretowania nazw plików w rozpakowanej wtyczce serwer pomocy szuka dokumentów najpierw w pliku doc.zip, a następnie w katalogu wtyczki. W przypadku używania odsyłacza argument elementu href jest określany względem bieżącej wtyczki. Rozważmy poniższy odsyłacz:
<topic label="Ref1" href="html/ref/ref1.html"/>
Wtyczka pomocy będzie szukać tego pliku w następujący sposób:
Pełny odsyłacz może być używany do odwoływania się do dowolnej treści w sieci WWW.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
System pomocy platformy używa do wyszukiwania przetłumaczonych plików tego samego schematu wyszukiwania w katalogach języków narodowych, którego używają pozostałe elementy platformy. (Opis tej struktury katalogów można znaleźć w sekcji Pliki charakterystyczne dla ustawień narodowych). W przypadku korzystania z pliku doc.zip należy utworzyć plik doc.zip dla każdego ustawienia narodowego i umieścić go w odpowiednim katalogu ustawienia narodowego. (Nie należy replikować struktury katalogów ustawień narodowych nl wewnątrz pliku doc.zip).
Podczas szukania zasobów pomocy oprócz katalogów ustawień narodowych system pomocy sprawdza również katalogi systemu okienkowego i systemu operacyjnego. Wyszukiwanie jest przeprowadzane do chwili znalezienia zasobu w następującej kolejności: podkatalogi ws, os, nl, a następnie katalog główny wtyczki. Dokumenty i inne zasoby, jak obrazy, których format może być inny w różnych systemach, powinny znajdować się w katalogu ws lub os określonej platformy.
Argument elementu href może się odwoływać również do treści innej wtyczki. Wystarczy użyć specjalnej notacji odwołań międzymodułowych, która jest interpretowana przez serwer pomocy:
<topic label="Ref1" href="PLUGINS_ROOT/identyfikator_innej_wtyczki/ref/ref1.html"/>
W tym przypadku zmienna PLUGINS_ROOT
zostaje zinterpretowana z chwilą uruchomienia skryptu i zastąpiona katalogiem głównym wtyczek. Element identyfikator_innej_wtyczki
można zastąpić własnym identyfikatorem wtyczki. Temat z odsyłaczem do tego rozdziału podręcznika programisty wyglądałby następująco:
<topic label="Rozdział pomocy w dokumentacji platformy" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
W wersjach wcześniejszych niż wersja 3.2 odwołania do dokumentów zawartych w innych wtyczkach realizowano poprzez wpisanie elementu "..", za pomocą którego przechodzono w górę na poziom wtyczek, a następnie tworzono odwołanie do identyfikatora wtyczki, po którym następowało odwołanie HREF do tematu w ramach danej wtyczki. Obecnie zaleca się stosowanie zmiennej PLUGINS_ROOT
zamiast elementu "..". Korzystanie z tej zmiennej pozwala uniknąć przechodzenia na wyższe lub niższe poziomy struktury katalogów. Poza tym można ją stosować we wszystkich adresach URL zasobów w dokumentach pomocy (obrazy, odsyłacze, pliki CSS, pliku JavaScript itd.).
Uwaga: W przypadku odwoływania się do treści innej wtyczki należy się upewnić, że zastosowany został identyfikator wtyczki zadeklarowany w jego pliku plugin.xml, a nie nazwa jej katalogu. Mimo że w praktyce nazwy te są często identyczne, to istotne jest, aby sprawdzić, czy używany jest identyfikator, a nie nazwa katalogu.
Informacje o marce są często umieszczane we wtyczce definiującej produkt,
jak opisano to w temacie Definiowanie produktu. Do zasobów pomocy we wtyczce można odnosić się z poziomu spisu treści lub tematów, korzystając ze specjalnego identyfikatora PRODUCT_PLUGIN
zastępującego identyfikator wtyczki. Na przykład:
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
odwołuje się do arkusza stylów znajdującego się we wtyczce aktualnie uruchomionego produktu.