Spis treści

org.eclipse.help.toc

Punkt rozszerzenia służący do rejestrowania treści pomocy elektronicznej dla określonego modułu dodatkowego.

Każdy moduł dodatkowy, który stanowi źródło plików pomocy, powinien spełniać następujące warunki:

Opcjonalnie indeks wyszukiwania może zostać wstępnie zbudowany i zarejestrowany przy użyciu elementu index, aby zapewnić wysoką wydajność już w trakcie wykonywania pierwszej próby wyszukiwania. Dla modułu dodatkowego można zarejestrować tylko jeden indeks - rejestracja wielu elementów index spowoduje nieokreślone zachowanie.

<!ELEMENT extension (toc* , index?)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT toc EMPTY>

<!ATTLIST toc

file     CDATA #REQUIRED

primary  (true | false) "false"

extradir CDATA #IMPLIED>


<!ELEMENT index EMPTY>

<!ATTLIST index

path CDATA #REQUIRED>

Dostępny od wersji 3.1 opcjonalny element, który umożliwia deklarację wstępnie zbudowanego indeksu wyszukiwania, tworzonego z dokumentów wnoszonych w ramach tego modułu dodatkowego.



Poniżej przedstawiono przykład użycia punktu rozszerzenia toc.

(w pliku plugin.xml)

 

<extension point=

"org.eclipse.help.toc"

>

<toc file=

"maindocs.html"

primary=

"true"

/>

<toc file=

"task.xml"

/>

<toc file=

"sample.xml"

extradir=

"samples"

/>

<index path=

"index/"

/>

</extension>

(w pliku maindocs.xml)

<toc label="Przykład systemu pomocy">
 <topic label="Wstęp" href="intro.html"/>
 <topic label="Czynności">
  <topic label="Tworzenie projektu" href="tasks/task1.html">
   <topic label="Tworzenie projektu WWW" href="tasks/task11.html"/>
   <topic label="Tworzenie projektu Java" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testowanie projektu" href="tasks/taskn.html"/>
 </topic>
 <topic label="Przykłady">
  <topic label="Tworzenie projektu Java" href="samples/sample1.html">
   <topic label="Uruchamianie kreatora" href="samples/sample11.html"/>
   <topic label="Ustawianie opcji" href="samples/sample12.html"/>
   <topic label="Kończenie tworzenia projektu" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(w pliku tasks.xml)

<toc label="Budowanie projektu">
 <topic label="Budowanie projektu" href="build/building.html">
  <topic label="Budowanie projektu WWW" href="build/web.html"/>
  <topic label="Budowanie projektu Java" href="build/java.html"/>
 </topic>
</toc>


(w pliku samples.xml)

<toc link_to="maindocs.xml#samples" label="Korzystanie z narzędzia do kompilacji">
 <topic label="Przykład narzędzia do kompilacji" href="compilesample/example.html">
  <topic label="Krok 1" href="compilesample/step1.html"/>
  <topic label="Krok 2" href="compilesample/step2.html"/>
  <topic label="Krok 3" href="compilesample/step3.html"/>
  <topic label="Krok 4" href="compilesample/step4.html"/>
 </topic>
</toc>

Jeśli w ścieżce rozpoczynającej się od "samples" istnieje więcej dokumentów, nie będą one wyświetlane w drzewie nawigacji, ale będą dostępne do przeszukania.  Jest to możliwe dzięki zastosowaniu atrybutu "extradir" w elemencie <toc file="sample.xml" extradir="samples" /> w pliku plugin.xml. Przykładowo wyszukiwanie zwrotu "Tworzenie projektu Java" spowodowałoby zwrócenie dokumentu "Inne sposoby tworzenia projektu Java", którego ścieżka to samples/sample2.html.

Umożliwianie obsługi wersji narodowych Pliki TOC w formacie XML można przetłumaczyć, a wynikową kopię (z przetłumaczonymi etykietami) umieścić w katalogu nl/<język>/<kraj> lub nl/<język>. Oznaczenia <język> i <kraj> reprezentują dwuliterowe kody kraju i języka używane w oznaczeniach ustawień narodowych. Na przykład tłumaczenia na język chiński tradycyjny należy umieścić w katalogu nl/zh/TW. Katalog nl/<język>/<kraj> ma wyższy priorytet niż nl/<język>. Tylko gdy w katalogu nl/<język>/<kraj> nie zostanie znaleziony żaden plik, użyty zostanie plik znajdujący się w katalogu nl/<język>. Katalog główny modułu dodatkowego zostanie przeszukany na samym końcu.

Dokumentację zawartą w pliku doc.zip można udostępnić w wersjach narodowych przez utworzenie pliku doc.zip z przetłumaczonymi wersjami dokumentów i umieszczenie go w katalogu
nl/<język>/<kraj> lub nl/<język>. System pomocy będzie wyszukiwać pliki w tych katalogach przed domyślnym katalogiem modułu dodatkowego.
 

Do korzystania z tego punktu rozszerzenia nie jest potrzebny żaden kod. Wystarczy jedynie dostarczyć odpowiednie pliki manifestu wymienione w pliku plugin.xml.

Domyślna implementacja interfejsu użytkownika systemu pomocy dostarczanego wraz z platformą Eclipse obsługuje w pełni punkt rozszerzenia toc.