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>
Znaczniki konfiguracji dla pliku TOC:
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!ELEMENT topic (topic | anchor | link )*
>
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED >
<!ELEMENT anchor EMPTY >
<!ATTLIST anchor id ID #REQUIRED >
<!ELEMENT link EMPTY >
<!ATTLIST link toc CDATA #REQUIRED >
Zgodnie z ogólną zasadą moduł dodatkowy stanowiący źródło pomocy elektronicznej definiuje własne pliki TOC. System pomocy jest konfigurowany do uruchomienia analogicznie do niektórych akcji i można w tym celu użyć ścieżki do pliku TOC.
Element topic (temat)
Wszystkie elementy tematu pomocy są dostarczane jako cześć elementu kontenera toc. Mogą mieć strukturę hierarchiczną albo przyjmować formę prostej listy.
Element topic to fundament struktury spisu treści. Jest on zwykle używany do dwóch celów:
1. Odsyłacz do pliku dokumentacji - zwykle jest to
plik HTML.
2. Kontener dla innego spisu treści w tym
samym lub w innym manifeście.
1. Tematy jako odsyłacze
Najprostsze użycie tematu to odsyłacz do pliku dokumentacji.
<topic label="Plik na temat wybranego pojęcia" href="concepts/some_file.html" />
Atrybut href jest określany względem modułu dodatkowego, do którego należy plik manifestu. Jeśli zachodzi potrzeba uzyskania dostępu do innego modułu dodatkowego, można użyć składni
<topic label="Temat w innym module dodatkowym" href="../other.plugin.id/concepts/some_other_file.html" />
2. Tematy jako kontenery
Drugim najpowszechniejszym użyciem tematu jest zastosowanie go w roli
kontenera dla innych elementów toc. Również sam temat-kontener może zawsze
odwoływać się do określonego pliku.
<topic label="Zintegrowane środowisko programistyczne"
href="concepts/ciover.htm" >
<topic label="Uruchamianie środowiska IDE"
href="concepts/blah.htm" />
...
</topic>
Element link (odsyłacz)
Element link pozwala utworzyć odsyłacz do innego spisu treści zdefiniowanego w innym pliku TOC. Wszystkie tematy z pliku TOC określonego przez atrybut toc zostaną wyświetlone w spisie treści, tak jakby były zdefiniowane bezpośrednio zamiast elementu odsyłacza. Aby uwzględnić spis treści z pliku api.xml, można posłużyć się następującym zapisem:
<topic label="Informacje dodatkowe" >
...
<link toc="api.xml" />
...
</topic>
Element anchor (zakotwiczenie)
Element anchor definiuje punkt, który pozwoli dołączyć inne pliki TOC do bieżących opcji nawigacji, poszerzając je bez użycia elementu odsyłacza i bez odwoływania się do innych plików TOC. Aby umożliwić wstawienie spisu treści z większą liczbą tematów po dokumencie "ZZZ" można zdefiniować zakotwiczenie w następujący sposób:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Element toc (spis treści)
Element toc to spis treści, który grupuje tematy i inne elementy zdefiniowane w tym pliku. Etykieta identyfikuje spis treści podczas wyświetlania go przez użytkownika. Opcjonalny atrybut topic to ścieżka do pliku tematu opisującego dany spis treści. Opcjonalny atrybut link_to umożliwia połączenie elementu toc z tego pliku z innym plikiem toc, który znajduje się wyżej w hierarchii nawigacji. Wartość atrybutu link_to musi określać zakotwiczenie w innym pliku toc. Aby połączyć element toc z pliku myapi.xml z plikiem api.xml określonym w innym module dodatkowym należałoby użyć składni:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Interfejs API
mojego narzędzia"/>
...
<toc />
gdzie znak # oddziela nazwę pliku toc od identyfikatora zakotwiczenia.
<!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.
index/
, nl/ja/JP/index/
, nl/en/US/index/
itp.).(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.
Copyright (c) 2000, 2005 IBM Corporation i inne podmioty.
Wszelkie prawa zastrzeżone. Program ten oraz towarzyszące mu materiały są udostępniane na warunkach licencji EPL (Eclipse Public License), wersja 1.0, dołączonej do nich i dostępnej pod adresem http://www.eclipse.org/legal/epl-v10.html.