Hver plugin-modul som har hjelpefiler, bør generelt gjøre dette:
En søkeindeks
kan valgfritt forhåndsbygges og registreres ved hjelp av et index
-element for å
utføre det første søkeforsøket. Bare en indeks
per plugin-modul kan registreres - flere index
-elementer vil gi en udefinert virkemåte.
<!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>
Konfigurasjonskoding for TOC-filen:
<!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 >
Generelt sett må en plugin-modul som må vise hjelp, definere egne TOC-filer. Hjelpefunksjonen er konfigurert til å bli startet som noen handlinger, og TOC-filens bane kan brukes til å gjøre det.
topic-elementet
Alle hjelpeemneelementer er en del av TOC-containerelementet. De kan ha en hierarkisk struktur, eller de kan vises som en flat fil.
topic-elementet er arbeidshesten i innholdsfortegnelsen. Det finnes to vanlige bruksområder for topic-elementet:
1. Å sørge for en link
til en dokumentasjonsfil - vanligvis en HTML-fil.
2. Å fungere som en
container for andre TOC-filer, enten i samme manifest eller i et annet.
1. Emner som linker
Den enkleste
bruken av et emne er som en link til en dokumentasjonsfil.
<topic label="Some concept file" href="concepts/some_file.html" />
Attributtet href er relativt for plugin-modulen som manifestfilen tilhører. Hvis du må ha tilgang til en fil i en annen plugin-modul, kan du bruke denne syntaksen:
<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Emner som containere
Den nest vanligste bruken
av et emne er å bruke det som en container for en annen TOC-fil. Selve
containeremnet kan i tillegg alltid referere til en bestemt fil.
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
link-lementet
Med link-elementet kan det linkes til en innholdsfortegnelse som er definert i en annen TOC-fil. Alle emnene fra TOC-filen som er oppgitt i toc-attributtet, blir vist i innholdsfortegnelsen som om de var definert direkte, i stedet for link-elementet. Hvis du vil inkludere toc fra api.xml-filen, kan du skrive dette:
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
anchor-elementet
anchor-elementet definerer et punkt som vil tillate linking av andre toc-filer til denne navigeringen, og utviding av den, uten å bruke link-elementet og referere til andre toc-filer derfra. Hvis du vil tillate at det settes inn en innholdsfortegnelse med flere emner etter "ZZZ"-dokumentet, definerer du et anker på denne måten:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
toc-elementet
toc-elementet er en innholdsfortegnelse som grupperer emner og andre elementer som er definert i denne filen. Etiketten identifiserer innholdsfortegnelsen for brukeren når den blir vist. Det valgfrie topic-attributtet er banen til en emnefil som beskriver innholdsfortegnelsen. Det valgfrie link_to-attributtet tillater linking av innholdsfortegnelsen fra denne filen til en annen toc-fil som er høyere oppe i navigeringshierarkiet. Verdien av link_to-attributtet må oppgi et anker i en annen toc-fil.Hvis du vil linke toc fra myapi.xml- til api.xml-filen, som er oppgitt i en annen plugin-modul, bruker du denne syntaksen:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
der tegnet # skiller navnet på toc-filen fra ankeridentifikatoren.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Siden 3.1) et valgfritt element som tillater deklarering av en forhåndsbygd søkeindeks som er opprettet fra dokumenter fra denne plugin-modulen.
index/
, nl/ja/JP/index/
,
nl/en/US/index/
).(i filen 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>
(i filen maindocs.xml)
<toc label="Help System Example">
<topic label="Introduction" href="intro.html"/>
<topic label="Tasks">
<topic label="Creating a Project" href="tasks/task1.html">
<topic label="Creating a Web Project" href="tasks/task11.html"/>
<topic label="Creating a Java Project" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Testing a Project" href="tasks/taskn.html"/>
</topic>
<topic label="Samples">
<topic label="Creating Java Project" href="samples/sample1.html">
<topic label="Launch a Wizard" href="samples/sample11.html"/>
<topic label="Set Options" href="samples/sample12.html"/>
<topic label="Finish Creating Project" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(i filen tasks.xml)
<toc label="Building a Project">
<topic label="Building a Project" href="build/building.html">
<topic label="Building a Web Project" href="build/web.html"/>
<topic label="Building a Java Project" href="build/java.html"/>
</topic>
</toc>
(i filen samples.xml)
<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
<topic label="The Compile Tool Sample" 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>
Hvis det finnes flere dokumenter med en bane som begynner med "samples", blir de ikke vist i navigeringstreet, men de blir tilgjengelige gjennom søk. Dette skyldes at attributtet "extradir" finnes i elementet <toc file="sample.xml" extradir="samples" /> inside plugin.xml file.Et søk etter "Creating Java Project" kan for eksempel returnere dokumentet "Other Ways of Creating Java Project", som har banen samples/sample2.html.
Internasjonalisering TOC XML-filene kan oversettes, og resultatet (med oversatte etiketter) bør legges i katalogen nl/<språk>/<land> eller nl/<språk>. <språk> og <land> står for språk- og landkoder på to bokstaver som brukes i språkmiljøkoder. Oversettelser til tradisjonell kinesisk legges for eksempel i katalogen nl/zh/TW. Katalogen nl/<språk>/<land> har høyere prioritet enn nl/<språk>. Bare hvis det ikke blir funnet en fil i nl/<språk>/<land>, vil filen som ligger i nl/<språk> bli brukt. Rotkatalogen for en plugin-modul blir søkt i sist.
Dokumentasjonen i doc.zip
kan lokaliseres ved å opprette en doc.zip-fil med oversatte versjoner
av dokumenter, og legge doc.zip i katalogen nl/<språk>/<land> eller
nl/<språk>. Hjelpefunksjonen leter etter
filene under disse katalogene før standard plugin-katalog brukes.
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