Minden egyes bedolgozó, amely súgófájlokat tesz közzé, általában a következő tevékenységeket végzi:
Nem kötelező módon egy keresőindex előregyártható és bejegyezhető az
index
elem használatával az első keresési kísérlet
végrehajtásához. Bedolgozónként csak egy index jegyezhető be, a több
index
elem meghatározatlan viselkedést eredményez.
<!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>
TOC fájl beállítási leírónyelve:
<!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 >
Az online súgót biztosító bedolgozók általában saját TOC fájlokat határoznak meg. Végső soron a súgórendszer úgy van beállítva, hogy bizonyos tevékenységeket elindítson, és a TOC fájl elérési útja használható erre.
A témakör elem
A Témakörök valamennyi eleme a toc tárolóelem részeként működik közre. Lehetnek hierarchikus szerkezetbe szervezve, de lehetnek egyszerű lapos listaként felsorolva is.
A témakör elem a tartalomjegyzék szerkezetének igavonója. A témakör elemnek két jellemző felhasználási köre van:
1. Hivatkozás nyújt
egy dokumentációs fájlra (ez általában egy html fájl).
2. Másik toc tárolójaként működik ugyanabban a leírófájlban vagy
másikban.
1. Témakörök hivatkozásként
Egy témakör a legegyszerűbben dokumentációs fájlra mutató
hivatkozásként használható fel.
<topic label="Néhány alapelv fájl" href="concepts/some_file.html" />
A href attribútum ahhoz a bedolgozóhoz viszonyított, amelyhez a leírófájl tartozik. Másik bedolgozóban található fájl eléréséhez a következő szintaxis használható:
<topic label="témakör egy másik bedolgozóban" href="../other.plugin.id/concepts/some_other_file.html" />
2. Témakörök tárolóként
A második leggyakoribb felhasználása a témaköröknek más toc.
fájlok tárolójaként történik.
<topic label="Integrált fejlesztői
környezet" href="concepts/ciover.htm" >
<topic label="Az IDE indítása" href="concepts/blah.htm"
/>
...
</topic>
A link elem
A hivatkozás elem segítségével egy másik toc fájlban meghatározott tartalomjegyzékre lehet hivatkozni. A toc fájlnak a attribútumban meghatározott valamennyi témaköre megjelenik a tartalomjegyzékben, mintha közvetlenül a hivatkozás elem helyén lennének meghatározva. TOC beillesztése api.xml fájlból a következőképpen lehetséges:
<topic label="Hivatkozások" >
...
<link toc="api.xml" />
...
</topic>
Az anchor (horgony) elem
Az anchor elem egy pontot határoz meg, amely lehetővé teszi más toc fájlok ezen navigációval összeszerkesztését és kiterjesztését a link elem használata és más innen származó toc fájl hivatkozása nélkül. Ha lehetővé kívánja tenni egy tartalomjegyzék beszúrását további témakörökkel a "ZZZ" dokumentum után, akkor így kell megadnia egy horgonyt:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
A toc elem
A toc elem egy olyan tartalomjegyzék, amely az ebben a fájlban meghatározott témaköröket és más elemeket csoportosítja. A felhasználó számára a megjelenített címke azonosítja a tartalomjegyzéket. A nem kötelező topic attribútum a TOC-t leíró témakör fájl elérési útja. Az elhagyható link_to attribútum lehetővé teszi, hogy a toc ebből a fájlból egy másik, a navigációs hierarchiában feljebb lévő toc fájlba hivatkozzon. A link_to attribútum értékének egy másik toc fájlban lévő horgonyt kell meghatároznia. TOC csatolása a myapi.xml fájlból egy másik bedolgozóban meghatározott api.xml fájlba a következő szintaxis szerint történik:
<toc
link_to="../anotherPlugin/api.xml#moreapi" label="Saját eszköz API"/>
...
<toc />
ahol a # karakter választja el a toc fájlnevet a horgony azonosítótól.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(3.1 változat óta) elhagyható elem, amely lehetővé teszi az ezen bedolgozó által hozzáadott dokumentumokból létrehozott előregyártott keresési index deklarálását.
index/
, nl/ja/JP/index/
,
nl/en/US/index/
, stb.).(a plugin.xml fájlban)
<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>
(a maindocs.xml fájlban)
<toc label="Súgórendszer példa">
<topic label="Bevezetés" href="intro.html"/>
<topic label="Feladatok">
<topic label="Projekt létrehozása" href="tasks/task1.html">
<topic label="Webprojekt létrehozása" href="tasks/task11.html"/>
<topic label="Java projekt létrehozása" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Projekt tesztelése" href="tasks/taskn.html"/>
</topic>
<topic label="Minták">
<topic label="Java projekt létrehozása" href="samples/sample1.html">
<topic label="Varázsló indítása" href="samples/sample11.html"/>
<topic label="Paraméterek beállítása" href="samples/sample12.html"/>
<topic label="Projekt létrehozásának befejezése" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(a tasks.xml fájlban)
<toc label="Projekt összeépítése">
<topic label="Projekt összeépítése" href="build/building.html">
<topic label="Webprojekt összeépítése" href="build/web.html"/>
<topic label="Java projekt összeépítése" href="build/java.html"/>
</topic>
</toc>
(a samples.xml fájlban)
<toc link_to="maindocs.xml#samples" label="A fordítási eszköz használata">
<topic label="Fordítási eszköz példa" href="compilesample/example.html">
<topic label="1. lépés" href="compilesample/step1.html"/>
<topic label="2. lépés" href="compilesample/step2.html"/>
<topic label="3. lépés" href="compilesample/step3.html"/>
<topic label="4. lépés" href="compilesample/step4.html"/>
</topic>
</toc>
Mivel több dokumentum rendelkezik "samples" kezdetű elérései úttal, ezért ezek nem jelennek meg a navigációs fában, keresés használatával azonban elérhetők. Ezt a plugin.xml fájlban lévő <toc file="sample.xml" extradir="samples" /> elem "extradir" attribútumának jelenléte okozza. Például a "Java projekt létrehozása" kifejezésre keresés visszaadhatná a "Java projekt létrehozásának további módjai" dokumentumot, amelynek elérési útja samples/sample2.html.
Nemzetközivé tétel A TOC XML fájlok lefordíthatók, az eredményül kapott másolatokat (a lefordított címkékkel) pedig az nl/<language>/<country> vagy az nl/<language> könyvtárban kell elhelyezni. A <language> és <country> két betűs nyelv- és országkódokat képviselnek a helyi kódokban használtak szerint. Például a hagyományos kínai fordításokat az nl/zh/TW könyvtárban kell elhelyezni. Az nl/<language>/<country> könyvtár az nl/<language> könyvtárnál magasabb prioritással rendelkezik. Az nl/<language> könyvtárban található fájl csak akkor kerül felhasználásra, ha az nl/<language>/<country> könyvtár üres. A bedolgozó gyökérkönyvtárának átnézése az utolsó.
A doc.zip fájlban
tárolt dokumentáció a következőképpen honosítható: a dokumentációk
lefordított változatának felhasználásával kell létrehozni a doc.zip fájlt,
majd el kell helyezni az
nl/<language>/<country> vagy az
nl<language> könyvtárban. A súgórendszer a fájlokat ezekben a
könyvtárakban fogja keresni mielőtt rátérne az alapértelmezett bedolgozó
könyvtárra.
Copyright (c) 2000, 2005 IBM Corporation és mások.
Minden jog fenntartva. Jelen program és annak kísérőanyagai a csomaghoz
tartozó, illetve a
http://www.eclipse.org/legal/epl-v10.html
címen is elérhető Eclipse Public License 1.0 verziójának hatálya alatt lettek
közzétéve.