Serwer pomocy i położenia plików

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

Dokumentacja przetłumaczona na język narodowy

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.

Odwołania między wtyczkami

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.

Odwoływanie się do wtyczki produktu

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.