Voor elke plugin met helpbestanden geldt over het algemeen het volgende:
U kunt eventueel een zoekindex vooraf bouwen en registreren met het element index
, zodat u een eerste zoekopdracht kunt uitvoeren. Per plugin kunt u één index registreren; het definiëren van meerdere index
-elementen leidt tot onvoorspelbaar gedrag.
<!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>
Configuratiemarkup voor TOC-bestand:
<!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 >
Normaal gesproken wordt een inhoudsopgavebestand gedefinieerd voor een plugin met online Help. Het Help-systeem wordt uiteindelijk geconfigureerd om te starten, hetgeen u later kunt bereiken met bepaalde acties en het pad naar het inhoudsopgavebestand.
Het element topic
Alle Help-onderwerpen worden als onderdeel van de inhoudsopgave toegevoegd. De elementen kunnen zowel een hiërarchische als een platte structuur hebben.
Het element topic vormt de structuur van de inhoudsopgave en wordt op twee manieren gebruikt: Er zijn twee gangbare manieren van gebruik voor het element topic:
1. Als link naar een ander documentatiebestand (meestal een HTML-bestand)
2. Als container voor een andere inhoudsopgave, in hetzelfde of een ander manifest.
1. Onderwerpen als links
Het instellen van een onderwerp als link naar een documentatiebestand is het eenvoudigste gebruik.
<topic label="Een conceptbestand" href="concepts/some_file.html" />
Het kenmerk href is relatief ten opzichte van de plugin waartoe het manifestbestand behoort. Als u een andere plugin wilt gebruiken, kunt u deze syntaxis gebruiken:
<topic label="Een onderwerp in een andere plugin" href="../other.plugin.id/concepts/some_other_file.html" />
2. Onderwerpen als containers
Onderwerpen worden ook vaak gebruikt als container voor andere inhoudsopgaven. Het onderwerp dat als container fungeert, kan zelf ook naar een bepaald bestand verwijzen.
<topic label="Geïntegreerde ontwikkelomgeving" href="concepts/ciover.htm" >
<topic label="De IDE starten" href="concepts/blah.htm" />
...
</topic>
Het element link
Het element link maakt het mogelijk links naar inhoudsopgaven te creëren die in een ander inhoudsopgavebestand zijn opgenomen. Alle onderwerpen uit het inhoudsopgavebestand die in het kenmerk toc zijn opgegeven, worden in de inhoudsopgave op dezelfde manier afgebeeld als wanneer ze rechtstreeks in het link-element zouden zijn gedefinieerd. U kunt een inhoudsopgave uit een bestand api.xml als volgt opnemen:
<topic label="Verwijzingen" >
...
<link toc="api.xml" />
...
</topic>
Het element anchor
Het element anchor definieert een punt waarmee andere inhoudsopgavebestanden links naar deze navigatie kunnen maken en deze kunnen uitbreiden zonder het element link te gebruiken en naar andere inhoudsopgavebestanden te verwijzen. U kunt een inhoudsopgave invoegen met meer onderwerpen na het document "ZZZ" door het element anchor als volgt te definiëren:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Het element toc
Het element toc is de inhoudsopgave waarin onderwerpen en andere in dit bestand gedefinieerde elementen worden gebundeld. De gebruiker kan de inhoudsopgave aan het label herkennen. Het optionele kenmerk topic is het pad naar het onderwerpsbestand waarin de inhoudsopgave wordt beschreven. Het optionele kenmerk link_to stelt u in staat een link te leggen tussen deze inhoudsopgave en een inhoudsopgave die hoger in de navigatiehiërarchie ligt. De waarde van het kenmerk link_to moet overeenkomen met een anchor-element in een ander inhoudsopgavebestand. U kunt een link tussen de inhoudsopgaven van de bestanden mijnapi.xml en api.xml (in een andere plugin) leggen met de volgende syntaxis:
<toc link_to="../eenAnderePlugin/api.xml#moreapi" label="Mijn tool-API"/>
...
<toc />
Hierbij geldt # als scheidingsteken tussen de naam van het inhoudsopgavebestand en de ankercode.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(vanaf 3.1) Een optioneel element waarmee u vooraf gebouwde zoekindices kunt declareren die zijn gemaakt op basis van documenten die door deze plugin zijn toegevoegd.
index/
, nl/ja/JP/index/
, nl/en/US/index/
enz.) (in bestand plugin.xml)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"toc1.xml"
primary=
"true"
/>
<toc file=
"toc2.xml"
primary=
"true"
category=
"mijnCategorie"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(in bestand maindocs.xml)
<toc label="Voorbeeld van Help-systeem">
<topic label="Inleiding" href="intro.html"/>
<topic label="Taken">
<topic label="Een project maken" href="tasks/task1.html">
<topic label="Een webproject maken" href="tasks/task11.html"/>
<topic label="Een Java-project maken" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Een project testen" href="tasks/taskn.html"/>
</topic>
<topic label="Voorbeelden">
<topic label="Een Java-project maken" href="samples/sample1.html">
<topic label="Een wizard starten" href="samples/sample11.html"/>
<topic label="Opties instellen" href="samples/sample12.html"/>
<topic label="Het maken van een project voltooien" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(in bestand tasks.xml)
<toc label="Een project bouwen">
<topic label="Een project bouwen" href="build/building.html">
<topic label="Een webproject bouwen" href="build/web.html"/>
<topic label="Een Java-project bouwen" href="build/java.html"/>
</topic>
</toc>
(in bestand samples.xml)
<toc link_to="maindocs.xml#samples" label="Het compileerprogramma gebruiken">
<topic label="Voorbeeld van het compileerprogramma" href="compilesample/example.html">
<topic label="Stap 1" href="compilesample/step1.html"/>
<topic label="Stap 2" href="compilesample/step2.html"/>
<topic label="Stap 3" href="compilesample/step3.html"/>
<topic label="Stap 4" href="compilesample/step4.html"/>
</topic>
</toc>
We gaan er in dit voorbeeld vanuit dat er meer documenten zijn waarvan het pad met "samples" begint. Deze worden niet afgebeeld in de navigatiestructuur maar kunnen wel doorzocht worden. Dit gedrag is ingesteld door het kenmerk "extradir" in het element <toc file="sample.xml" extradir="samples" /> in het bestand plugin.xml. Als u bijvoorbeeld zoekt naar "Een Java-project maken", kunt u het document "Een Java-project maken op andere manieren" (waarvan het pad samples/sample2.html is) opsporen.
Internationalisering De XML-inhoudsopgavebestanden kunnen worden vertaald. Vertaalde versies (met vertaalde labels) moeten in de directory's nl/<taal>/<land> of nl/<taal> worden geplaatst. De <taal> en het <land> worden aangeduid door een code van twee letters (zoals in locales). Een vertaling in traditioneel Chinees moet bijvoorbeeld in de directory nl/zh/TW worden geplaatst. De directory nl/<taal>/<land> heeft meer prioriteit dan nl/<taal>. Het bestand in de directory nl/<taal> wordt alleen gebruikt als de directory nl/<taal>/<land> leeg is. De hoofddirectory van de plugin wordt als laatste doorzocht.
U kunt de documentatie in het bestand doc.zip lokaliseren door de vertaalde versies in te pakken in het bestand doc.zip en dit ZIP-bestand in de directory nl/<taal>/<land> of nl/<taal> te plaatsen. Het Help-systeem zoekt eerst naar de bestanden in deze directory's voordat de plugindirectory als standaardinstelling wordt gebruikt.
Copyright (c) 2000, 2006 IBM Corporation en anderen.
Alle rechten voorbehouden. Dit programma en het begeleidende materiaal zijn beschikbaar gesteld onder de voorwaarden van de Eclipse Public License v1.0 die bij deze distributie is geleverd en beschikbaar is op http://www.eclipse.org/legal/epl-v10.html.