Ohjetiedostoja lisääville lisäosille yleensä kuuluvat tehtävät ovat
Hakutoiminnon ensimmäistä käyttökertaa voidaan haluttaessa nopeuttaa luomalla hakuindeksi etukäteen ja rekisteröimällä se index
-elementin avulla. Kutakin lisäosaa varten voi rekisteröidä vain yhden indeksin. Jos index
-elementtejä on useita, lisäosan toimintatapa ei ole määritysten mukainen.
<!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
category CDATA #IMPLIED>
Sisällysluettelotiedoston merkintärakenne on seuraava:
<!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 >
Yleensä lisäosa, joka toimittaa käytönaikaisen ohjeen, määrittää myös omat sisällysluettelotiedostot. Näin ohjejärjestelmä voidaan määrittää valmiiksi aloitusta varten tiettyjen toimintojen ja sisällysluettelotiedoston polun avulla.
Topic-elementti
Ohjeen ohjeaiheet määrittävät topic-elementit sisältyvät toc-elementtiin. Ne voidaan määrittää hierarkkisesti tai tasarakenteisesti.
Topic-elementit ovat sisällysluettelon merkintärakenteen monipuolisimpia elementtejä. Topic-elementtiä käytetään yleisesti seuraaviin kahteen tarkoitukseen:
1. Ohjetiedostojen (yleensä HTML-tiedostojen) linkitykseen.
2. Muiden samassa tai toisessa manifest-määrityksessä olevien toc-elementtien määritykseen.
1. Topic-elementtien käyttö linkitykseen
Topic-elementin yksinkertaisin käyttötapa on ohjetiedostojen linkitys:
<topic label="Jokin tiedosto" href="concepts/some_file.html"/>
Href-määritteen arvo on määritettävä suhteessa lisäosaan, johon manifest-tiedosto kuuluu. Jos halutaan käyttää jonkin toisen lisäosan tiedostoa, voidaan käyttää seuraavaa rakennetta:
<topic label="Toisen lisäosan ohjeaihe" href="../other.plugin.id/concepts/some_other_file.html" />
2. Topic-elementtien käyttö määritykseen
Toiseksi yleisin topic-elementtien käyttötapa on määrittää niihin
muita toc-elementtejä. Määrittävä topic-elementti voi sisältää myös
tiedostoviitteen:
<topic label="Integroitu kehitysympäristö" href="concepts/ciover.htm"
>
<topic label="IDE-ympäristön aloitus" href="concepts/blah.htm"
/>
...
</topic>
Link-elementti
Link-elementin avulla voidaan määrittää linkki toisessa sisällysluettelotiedostossa määritettyyn sisällysluetteloon. Kaikki link-elementin toc-määritteen mukaisen sisällysluettelotiedoston ohjeaiheet näkyvät sisällysluettelossa samalla tavalla kuin ne olisi määritetty suoraan. Esimerkiksi api.xml-tiedostoon määritetty sisällysluettelo lisättäisiin seuraavalla koodilla:
<topic label="Viitteet" >
...
<link toc="api.xml" />
...
</topic>
Anchor-elementti
Anchor-elementin avulla määritettävää ohjeen siirtymisnäkymää voidaan laajentaa määrittämällä piste, johon voidaan linkittää muita sisällysluettelotiedostoja. Tällöin linkitys voidaan tehdä ilman link-elementtiä ja viittauksia muihin sisällysluettelotiedostoihin. Esimerkiksi ZZZ-ohjeasiakirjan jälkeen sijoitettavia ohjeaiheita varten voidaan lisätä sisällysluettelolisäys seuraavalla koodilla:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Toc-elementti
Toc-elementti on sisällysluettelomääritys, joka määrittää ohjeaiheiden (topic-elementtien) ja muiden tässä tiedostossa määritettyjen elementtien ryhmittelyn. Käyttäjät näkevät label-määritteen mukaisen nimiön sisällysluetteloa tarkastellessaan. Valinnaisen topic-määritteen avulla voidaan määrittää sisällysluetteloa kuvaavan sisällysluettelotiedoston polku. Valinnaisen link_to-määritteen avulla voidaan linkittää tämän tiedoston sisällysluettelo siirtymishierarkian ylätasolla olevaan sisällysluettelotiedostoon. Link_to-määritteen arvon on oltava toisen sisällysluettelotiedoston anchor-elementin määritys.Esimerkiksi sisällysluettelon linkitys myapi.xml-tiedostosta toisessa lisäosassa määritettyyn api.xml-tiedostoon tehtäisiin seuraavasti:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Omat API-työkalut"/>
...
<toc />
#-merkki on sisällysluettelotiedoston nimen ja anchor-tunnisteen erotinmerkki.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Käytettävissä versiosta 3.1 alkaen.) Tämän valinnaisen elementin avulla voidaan esitellä tämän lisäosan lisäämistä asiakirjoista valmiiksi luotu hakuindeksi.
index/
, nl/fi/FI/index/
, nl/en/US/index/
ja niin edelleen.).(Määritystiedosto plugin.xml.)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"toc1.xml"
primary=
"true"
/>
<toc file=
"toc2.xml"
primary=
"true"
category=
"myCategory"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(Määritystiedosto maindocs.xml)
<toc label="Ohjejärjestelmäesimerkki">
<topic label="Johdanto" href="intro.html"/>
<topic label="Tehtävät">
<topic label="Projektin luonti" href="tasks/task1.html">
<topic label="Web-projektien luonti" href="tasks/task11.html"/>
<topic label="Java-projektien luonti" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Projektin testaus" href="tasks/taskn.html"/>
</topic>
<topic label="Mallit">
<topic label="Java-projektien luonti" href="samples/sample1.html">
<topic label="Ohjatun toiminnon aloitus" href="samples/sample11.html"/>
<topic label="Asetusten määritys" href="samples/sample12.html"/>
<topic label="Projektin luonnin viimeistely" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(Määritystiedosto tasks.xml)
<toc label="Projektin koonti">
<topic label="Projektin koonti" href="build/building.html">
<topic label="Web-projektien koonti" href="build/web.html"/>
<topic label="Java-projektien koonti" href="build/java.html"/>
</topic>
</toc>
(Määritystiedosto samples.xml)
<toc link_to="maindocs.xml#samples" label="Kääntötyökalun käyttö">
<topic label="Mallikääntötyökalu" href="compilesample/example.html">
<topic label="Vaihe 1" href="compilesample/step1.html"/>
<topic label="Vaihe 2" href="compilesample/step2.html"/>
<topic label="Vaihe 3" href="compilesample/step3.html"/>
<topic label="Vaihe 4" href="compilesample/step4.html"/>
</topic>
</toc>
Mikäli samples-alkuisessa polussa on useampia asiakirjoja, ne eivät näy siirtymisrakenteessa, mutta niitä voidaan käyttää hakutoiminnon avulla. Tämä johtuu siitä, että plugin.xml-tiedoston <toc file="sample.xml" extradir="samples" /> -elementti sisältää extradir-määritteen.Esimerkiksi hakuehto "Java-projektien luonti" voisi palauttaa polussa samples/sample2.html. olevan asiakirjan "Muut Java-projektien luontitavat".
Kansainvälistys Sisällysluettelon XML-tiedostot voidaan kääntää ja käännetyt tiedostot (joiden nimiöt on myös käännetty) sijoittaa hakemistoon nl/<kieli>/<maa> tai nl/<kieli>. Hakemistopolkujen <kieli>- ja <maa>-osat ovat paikallistunnuskoodien mukaiset kaksikirjaimiset kieli- ja maakoodit. Esimerkiksi perinteisen kiinan käännösten tallennushakemisto olisi nl/zh/TW. Nl/<kieli>/<maa>-hakemisto on ensisijainen nl/<kieli>-hakemistoon verrattuna. Nl/<kieli>-hakemistossa olevaa tiedostoa käytetään vain, jos tiedostoa ei löydy nl/<kieli>/<maa>-hakemistosta. Tiedostoa etsitään viimeisenä lisäosan päähakemistosta.
Doc.zip-arkistotiedoston sisältämät asiakirjat voidaan lokalisoida luomalla
doc.zip-tiedostosta käännetyt asiakirjat sisältävä versio ja tallentamalla se
nl/<kieli>/<maa>- tai nl/<kieli>-hakemistoon. Ohjejärjestelmä
etsii tiedostoja ensin näistä hakemistoista ja viimeisenä oletusarvoisesta
lisäosan hakemistosta.
Copyright (c) 2000, 2006 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html