Serwer pomocy i położenia plików

Aby udostępnić rzeczywiste strony WWW dokumentacji modułu dodatkowego, 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 modułami dodatkowymi. Podstawową różnicą dla programisty jest zwiększona elastyczność w sposobie ustalania struktury plików i określania odsyłaczy.

Moduł dodatkowy dokumentacji można uruchamiać z pliku JAR lub można go rozpakować podczas instalacji do katalogu modułów dodatkowych. Plik JAR archiwum modułu dodatkowego nie jest rozpakowywany do katalogu modułów dodatkowych, jeśli atrybut unpack elementu plugin w manifeście składnika ma wartość true. W takim module dodatkowym dokumentacja jest skompresowana w pliku JAR razem z innymi plikami modułu dodatkowego.

W modułach dodatkowych, 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 modułu dodatkowego. W przykładowym module dodatkowym 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 modułu dodatkowego.  W tym przypadku musi zawierać podkatalog html wraz z całą jego treścią.

W przypadku modułów dodatkowych 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 modułu dodatkowego nie jest obsługiwane przez system pomocy.

W trakcie interpretowania nazw plików w rozpakowanym module dodatkowym serwer pomocy szuka dokumentów najpierw w pliku doc.zip, a następnie w katalogu modułu dodatkowego. W przypadku używania odsyłacza argument elementu href jest określany względem bieżącego modułu dodatkowego. Rozważmy poniższy odsyłacz:

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

Moduł dodatkowy 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 modułu dodatkowego. 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 modułami dodatkowymi

Argument elementu href może się odwoływać również do treści innego modułu dodatkowego. Wystarczy użyć specjalnej notacji odwołań międzymodułowych, która jest interpretowana przez serwer pomocy:

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

Temat z odsyłaczem do tego rozdziału podręcznika programisty wyglądałby następująco:

   <topic label="Rozdział pomocy" href="../org.eclipse.platform.doc.isv/guide/help.html"/>

Uwaga: W przypadku odwoływania się do treści innego modułu dodatkowego należy się upewnić, że zastosowany został identyfikator modułu dodatkowego zadeklarowany w jego pliku plugin.xml, a nie nazwa jego 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 modułu dodatkowego produktu

Informacje o marce są często umieszczane w module dodatkowym definiującym produkt, jak opisano to w temacie Definiowanie produktu. Do zasobów pomocy w module dodatkowym produktu można się odwoływać z poziomu spisu treści lub tematów przy użyciu specjalnego identyfikatora "PRODUCT_PLUGIN" dla identyfikatora modułu dodatkowego. Na przykład:

   href="../PRODUCT_PLUGIN/book.css"

odwołuje się do arkusza stylów znajdującego się w module dodatkowym aktualnie uruchomionego produktu.