Z obecného hlediska by měl každý modul plug-in, který přispívá svými soubory nápovědy, dělat následující:
Vyhledávací rejstřík může být volitelně předem sestaven a zaregistrován pomocí prvku index
, aby se zvýšila efektivita při prvním pokusu vyhledávání. Pro jeden modul plug-in lze zaregistrovat pouze jeden rejstřík - přítomnost více prvků index
způsobí nedefinované chování.
<!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>
Konfigurační markup pro soubor s obsahem
<!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 >
Obecně si bude plug-in, který potřebuje poskytnout online nápovědu, definovat vlastní soubory s obsahem. Nakonec je systém nápovědy zkonfigurován, aby byl spuštěn jako určité akce, a k tomu je možné použít cestu k souboru s obsahem.
Prvek topic
Všechny prvky topic nápovědy jsou přidávány jako součást kontejnerového prvku toc. Mohou mít hierarchickou strukturu, nebo mohou být uvedeny v jednoduchém seznamu.
Prvek topic (heslo) je nosným prvkem struktury Obsahu. Existují dvě typická využití prvku topic:
1. Poskytnout odkaz na soubor s dokumentací - obvykle soubor HTML.
2. Chovat se jako kontejner pro ostatní obsahy, ať už ve stejném manifestu nebo v jiném.
1. Prvky topic jako odkazy
Nejjednodušší je použít prvek topic jako odkaz na soubor s dokumentací.
<topic label="Nějaký soubor konceptu" href="concepts/some_file.html" />
Atribut href je relativní vzhledem k modulu plug-in, k němuž patří soubor s manifestem. Pokud potřebujete přístup k souboru v jiném modulu plug-in, můžete použít syntaxi
<topic label="heslo v jiném modulu plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Prvky topic jako kontejnery
Druhým nejčastějším způsobem použití je použití prvku topic jako kontejneru pro jiné obsahy. I samotný kontejnerový prvek topic může vždy odkazovat na nějaký konkrétní soubor.
<topic label="Integrované vývojové prostředí" href="concepts/ciover.htm"
>
<topic label="Spuštění IDE" href="concepts/blah.htm"
/>
...
</topic>
Prvek link
Prvek link (odkaz) umožňuje odkaz na Obsah definovaný v jiném souboru s obsahem. Všechna hesla ze souboru s obsahem určená atributem toc se zobrazí v obsahu, jako by byla definovaná přímo na místě prvku link. Chcete-li zahrnout obsah ze souboru api.xml, můžete napsat
<topic label="Odkazy" >
...
<link toc="api.xml" />
...
</topic>
Prvek anchor
Prvek anchor (kotva) definuje bod, který umožní připojit k této navigaci další soubory s obsahem a rozšířit ji bez nutnosti používat prvek link a odkazovat odtud na ostatní soubory s obsahem. Kdybyste chtěli umožnit vložení Obsahu s dalšími hesly za dokumentem "ZZZ", definovali byste prvek anchor takto:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Prvek toc
Prvek toc (obsah) je Obsah, který seskupuje hesla a další prvky definované v tomto souboru. Označení identifikuje daný obsah uživateli, když se mu zobrazí. Volitelným atributem hesla nápovědy je cesta k souboru hesla, který popisuje daný obsah. Nepovinný atribut link_to umožňuje propojit obsah z tohoto souboru s jiným souborem s obsahem, který je na vyšším stupni navigační hierarchie. Hodnota atributu link_to musí udávat kotvu (anchor) v jiném souboru s obsahem. Kdybyste chtěli propojit obsah ze souboru myapi.xml se souborem api.xml, určeným v jiném modulu plug-in, použijete syntaxi
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Mé nástrojové API"/>
...
<toc />
Kde znak # odděluje název souboru s obsahem od identifikátoru kotvy.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Od verze 3.1) volitelný prvek umožňující deklaraci předem sestaveného vyhledávacího rejstříku vytvořeného z dokumentů přidaných tímto modulem plug-in.
index/
, nl/ja/JP/index/
, nl/en/US/index/
atd.).(v souboru 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>
(v souboru maindocs.xml)
<toc label="Příklad systému nápovědy">
<topic label="Úvod" href="intro.html"/>
<topic label="Úlohy">
<topic label="Vytváření projektu" href="tasks/task1.html">
<topic label="Vytváření webového projektu" href="tasks/task11.html"/>
<topic label="Vytváření projektu Java" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Testování projektu" href="tasks/taskn.html"/>
</topic>
<topic label="Ukázky">
<topic label="Vytváření projektu Java" href="samples/sample1.html">
<topic label="Spustit průvodce" href="samples/sample11.html"/>
<topic label="Nastavit volby" href="samples/sample12.html"/>
<topic label="Dokončit vytvoření projektu" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(v souboru tasks.xml)
<toc label="Sestavení projektu">
<topic label="Sestavení projektu" href="build/building.html">
<topic label="Sestavení webového projektu" href="build/web.html"/>
<topic label="Sestavení projektu Java" href="build/java.html"/>
</topic>
</toc>
(v souboru samples.xml)
<toc link_to="maindocs.xml#samples" label="Použití kompilačního nástroje">
<topic label="Ukázka kompilačního nástroje" href="compilesample/example.html">
<topic label="Step 1" href="compilesample/step1.html"/>
<topic label="Step 2" href="compilesample/step2.html"/>
<topic label="Step 3" href="compilesample/step3.html"/>
<topic label="Step 4" href="compilesample/step4.html"/>
</topic>
</toc>
Za předpokladu, že existuje více dokumentů s cestou začínající "samples", nebudou tyto dokumenty zobrazeny v navigačním stromě, ale budou dostupné pomocí vyhledávání. Důvodem je přítomnost atributu "extradir" v prvku <toc file="sample.xml" extradir="samples" /> uvnitř souboru plugin.xml . Například vyhledávání "Vytvoření projektu Java" může vrátit dokument "Jiné způsoby vytvoření projektu Java", jehož cesta je samples/sample2.html.
Internacionalizace Soubory s obsahem XML je možné přeložit a výsledná kopie (s přeloženými označeními) by měla být umístěna v adresáři nl/<jazyk>/<země> nebo nl/<jazyk>. <Jazyk> a <země> představují dvoupísmenné kódy jazyka a země, jaké se používají v kódech národních prostředí. Například překlady do tradiční čínštiny by měly být umístěny v adresáři nl/zh/TW. Adresář nl/<jazyk>/<země> má vyšší prioritu než adresář nl/<jazyk>. Pouze když nebude v adresáři nl/<jazyk>/<země> nalezen žádný soubor, použije se soubor umístěný v adresáři nl/<jazyk>. Nakonec bude prohledán kořenový adresář modulu plug-in.
Dokumentaci obsaženou v doc.zip je možné lokalizovat vytvořením souboru doc.zip s přeloženou verzí dokumentů a tento doc.zip umístit do
adresáře nl/<jazyk>/<země> nebo nl/<jazyk>. Systém nápovědy bude hledat soubory nejprve v těchto adresářích a teprve potom přejde do adresáře modulů plug-in.
Copyright (c) 2000, 2005 IBM Corporation a další.
Všechna práva vyhrazena.
Tento program a doprovodné materiály jsou zpřístupněny za podmínek licence Eclipse Public License
v1.0, která je součástí této distribuce a je k dispozici na adrese
http://www.eclipse.org/legal/epl-v10.html