Hver enkelt plugin, der leverer hjælpefiler, skal generelt gøre følgende:
Du kan også bygge et søgeindeks på forhånd og registrere det ved hjælp
af elementet index
for at optimere ydeevnen for det første
søgeforsøg. Du kan kun registrere ét indeks pr. plugin - flere
index
-elementer vil resultere i en ikke-defineret
funktionsmåde.
<!ELEMENT extension (toc* , index?)>
<!ATTLIST-udvidelse
point CDATA #REQUIRED
id CDATA #IMPLIED
navn CDATA #IMPLIED>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary (true | false) "false"
extradir CDATA #IMPLIED
category CDATA #IMPLIED>
Konfigurationskode for TOC-fil:
<!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 >
Normalt definerer en plugin, der skal levere onlinehjælp, sine egne TOC-filer. Til sidst konfigureres hjælpen til at starte som visse funktioner, og stien til TOC-filen kan bruges til dette.
Emneelementet
Alle hjælpeemne-elementer leveres som en del af TOC-opbevaringssteds-elementet. De kan have en hierarkisk struktur eller være opført på en enkel liste.
Emneelementet er centralt i indholdsfortegnelsens struktur. Der er to typiske anvendelser af emneelementet:
1. At levere et link til en dokumentationsfil, normalt en
HTML-fil.
2. At fungere som opbevaringssted for andre
indholdsfortegnelser, enten i den samme manifestfil eller en anden.
1. Emner som link.
Den mest almindelige brug af et emne er som link til en
dokumentationsfil.
<topic label="En begrebsfil" href="concepts/some_file.html" />
href-attributten henviser til den plugin, som manifestfilen hører til. Hvis du har brug for adgang til en fil i en anden plugin, kan du bruge syntaksen
<topic label="emne i en anden plugin" href="../other.plugin.id/concepts/some_other_file.html" />
2. Emner som opbevaringssteder
Den næstalmindeligste måde at bruge et emne på er at bruge det som
opbevaringssted for andre indholdsfortegnelser. Emnet selv kan altid
henvise til en bestemt fil også.
<topic label="Integreret udviklingsmiljø" href="concepts/ciover.htm"
>
<topic label="Start IDE'en" href="concepts/blah.htm"
/>
...
</topic>
Linkelementet
Med linkelementet kan du oprette link til en indholdsfortegnelse, der er defineret i en anden TOC-fil. Alle emnerne fra TOC-filen, der er anført i TOC-attributten, vises i indholdsfortegnelsen, som om de var defineret direkte for linkelementet. Du kan inkludere indholdsfortegnelsen fra api.xml ved at skrive
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
Ankerelementet
Ankerelementet definerer et punkt, som gør det muligt at oprette link fra andre TOC-filer til denne navigation og at udvide den uden at bruge linkelementet og uden at henvise til andre TOC-filer herfra. Hvis du vil indsætte en indholdsfortegnelse med flere emner efter "ZZZ"-dokumentet, skal du definere et anker som følger:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
TOC-elementet
TOC-elementet er en indholdsfortegnelse, der grupperer emner og andre elementer, der er defineret i denne fil. Etiketten identificerer indholdsfortegnelsen over for brugeren, når brugeren får den vist. Den valgfri emneattribut er stien til en emnefil, der beskriver indholdsfortegnelsen. Den valgfri attribut link_to gør det muligt at oprette link fra indholdsfortegnelsen i denne fil til en anden TOC-fil, der er højere oppe i navigationshierarkiet. Værdien for link_to-attributten skal angive et anker i en anden TOC-fil. Du kan oprette link fra myapi.xml-filen til api.xml-filen, der er angivet i en anden plugin, ved hjælp af syntaksen
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
hvor tegnet # adskiller TOC-filnavnet fra anker-id'en.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(siden 3.1) et valgfrit element, som gør erklæring mulig af et forudbygget indeks oprettet på basis af dokumenter, der er leveret af denne plugin.
index/
,
nl/ja/JP/index/
, nl/en/US/index/
osv.).(i filen plugin.xml)
<udvidelsespunkt=
"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="Eksempel på hjælp">
<topic label="Introduktion" href="intro.html"/>
<topic label="Tasks">
<topic label="Opret et projekt" href="tasks/task1.html">
<topic label="Opret et web-projekt" href="tasks/task11.html"/>
<topic label="Opret et Java-projekt" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Test et projekt" href="tasks/taskn.html"/>
</topic>
<topic label="Eksempler">
<topic label="Opret et Java-projekt" href="samples/sample1.html">
<topic label="Start en guide" href="samples/sample11.html"/>
<topic label="Angiv valg" href="samples/sample12.html"/>
<topic label="Afslut oprettelse af projekt" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(i filen tasks.xml)
<toc label="Byg et projekt">
<topic label="Bygning af et projekt" href="build/building.html">
<topic label="Byg et web-projekt" href="build/web.html"/>
<topic label="Byg et Java-projekt" href="build/java.html"/>
</topic>
</toc>
(i filen samples.xml)
<toc link_to="maindocs.xml#samples" label="Brug af kompileringsværktøjet">
<topic label="Eksempel på kompileringsværktøjet" 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 der findes flere dokumenter med en sti, der begynder med "samples", bliver de ikke i navigationstræstrukturen, men kan vises ved hjælp af søgning. Det skyldes attributten "extradir" i elementet <toc file="sample.xml" extradir="samples" /> i filen plugin.xml . Hvis du f.eks. søger efter "Opret et Java-projekt", kan resultatet være et dokument "Andre måder at oprette et Java-projekt på", hvis sti er samples/sample2.html.
Internationalisering TOC XML-filerne kan oversættes, og den resulterende kopi (med oversatte etiketter) skal placeres i nl/<language>/<country> eller nl/<language> directory. <language> og <country> står for sprog- og landekoder på to bogstaver, som anvendt i forbindelse med koder for sprogkonventioner. Oversættelser til uforkortet kinesisk skal f.eks. placeres i biblioteket nl/zh/TW. Biblioteket nl/<language>/<country> har højere prioritet end nl/<language>. Det er kun, hvis der ikke findes nogen fil i nl/<language>/<country>, at filen i nl/<language> bliver benyttet. Der vil blive søgt i rodbiblioteket for en plugin til sidst.
Dokumentationen i doc.zip kan lokaliseres ved at oprette en doc.zip-fil
med de oversatte versioner af dokumenterne og placere doc.zip i
biblioteket nl/<language>/<country> eller nl/<language>.
Hjælpen vil lede efter filer under disse biblioteker, inden det
anvender plugin-biblioteket.
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