Kohdeohjesisällön kuvaus ja pakkaaminen

Kohdeohjeet kuvataan liittämällä käyttöliittymän koodissa esitelty kontekstitunnus kuvaukseen ja käytönaikaisen ohjeen asiaan liittyvien ohjeaiheiden linkkiluetteloon.  Nämä liitännät tehdään XML-tiedoston sisällä. Voit luoda kuinka monta tahansa sellaista XML-tiedostoa, jossa on kohdeohjeen liitännät kullekin lisäosalle. Kunkin kontekstitunnuksen kuvaus ja linkit toteutetaan XML-tiedoston <context>-elementtien sisällä. Kullakin kontekstielementillä voi olla valinnainen <description>-elementti, jonka avulla kuvataan käyttöliittymän objekti, ja miten monta tahansa sellaista <topic>-elementtiä, joka muodostaa linkin käytönaikaiseen ohjeeseen.

Versiosta 3.1 lähtien kontekstielementit voivat valinnaisesti ohittaa oletusotsikon, jonka avulla tilannekohtaiset ohjetiedot esitellään Ohje-näkymässä.

<contexts>
	<context id="panic_button" title="Panic Button Title">
		<description>This is the panic button.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/>
		<topic href="reference/panic_button.htm" label="Panic Button Reference"/>
	</context>
	...
</contexts>

Kun kontekstit on kuvattu XML-tiedostossa tai -tiedostoissa, voit viitata lisäosan manifest-tiedoston kontekstitiedostoihin. Huomaa, että edellä oleva kontekstitunnus ei ole tarkka. Tämä on sallittua, kunhan kontekstitiedosto on lisätty sen lisäosan manifest-tiedostoon, joka määrittää kontekstitunnuksen. Toisin sanoen kontekstitunnus tulkitaan sen lisäosan tunnukseksi, joka on lisännyt XML-tiedoston.  

Lisäosa lisää kontekstitiedostot laajennuspisteen org.eclipse.help.contextsavulla.  

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
</extension>

Voit viitata muiden lisäosien kontekstitiedostoihin sisällyttämällä plugin-määritteen. Sen avulla voit ryhmittää kaiken dokumentaation, myös kohdeohjeet, yhteen lisäosaan ja viitata siihen käyttöliittymäkoodin lisäosasta tai jostakin muusta asiaan liittyvästä lisäosasta.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
</extension>

Kontekstit voi siis järjestää joustavasti yhdeksi tai useaksi tiedostoksi yhteen tai useaan lisäosaan. Tärkeintä on, että tiedostojen kontekstitunnukset tulkitaan oikein. Jos et tarkenna kontekstitunnusta täysin, kontekstin XML-tiedostot on lisättävä lisäosaan, joka esittelee kontekstitunnukset. Jos käytät tarkkoja kontekstitunnuksia XML-kontekstitiedostossa, voit määrittää joustavasti XML-tiedostojen sijainnin ja sen, mikä lisäosa lisää kontekstin.

Kohdeohje useista lisäosista

Joustavuutta parantaa mahdollisuus lisätä saman kontekstitunnuksen kohdeohjeita eri lisäosista. Tämä on hyödyllistä esimerkiksi silloin, kun käytössä on eri dokumentaatiolisäosien joukkoja, jotka on ehkä asennettu käyttäjän kokoonpanoon. Tällöin kukin dokumentaatiolisäosa voi esitellä kontekstinsa itsenäisesti. Käyttäjä näkee kaikkien widget-objektin tunnukseen konteksteja lisänneiden lisäosien yhdistetyn tilannekohtaisen ohjesisällön.

Huomaa, että on käytettävä tarkkaa widget-objektin kontekstitunnusta, koska mikään dokumentaatiolisäosista ei esitellyt kontekstitunnusta. Kun useat lisäosat lisäävät kohdeohjeen samalle kontekstitunnukselle, ensin tulee näkyviin kontekstin esitelleen lisäosan (käyttöliittymälisäosan) sisältö. Lisäkuvaukset ja -linkit liitetään vapaassa järjestyksessä.

Dynaaminen sisältö

Dynaamista sisältöä voi käyttää kohdeohjeissa suodattamalla kohdeohjeen aihelinkkejä. Voi olla hyödyllistä, että esimerkiksi jokin ohjeaihe näkyy kohdeohjeessa vain, jos käytössä on tietty käyttöjärjestelmä.