Varje insticksprogram som bidrar med hjälpfiler bör i allmänhet göra följande:
Om så önskas kan ett sökindex byggas i förväg och registreras med hjälp av elementet index
för att ge bättre prestanda vid det första sökförsöket. Endast ett index per insticksprogram kan registreras - flera index
-element ger oförutsägbara resultat.
<!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>
Konfigurationsmärkord för innehållsförteckningsfil:
<!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 >
I allmänhet definierar att insticksprogram som tillhandahåller direkthjälp sina egna innehållsförteckningsfiler. I slutänden konfigureras hjälpsystemet så att det startas som vissa åtgärder, och innehållsförteckningsfilens sökväg kan användas till att göra detta.
Avsnittselementet
Alla hjälpavsnittselement tillhandahålls som en del av behållarelementet för innehållsförteckning. De kan ha en hierarkisk struktur eller så kan de anges i en platt lista.
Avsnittselementet är arbetshästen för innehållsförteckningens struktur. Det finns två typiska användningssätt för avsnittselementet:
1. För att tillhandahålla en länk till en dokumentationsfil - vanligen en HTML-fil.
2. För att fungera som en behållare för annan innehållsförteckning, i samma manifest
eller ett annat.
1. Avsnitt som länkar
Den enklaste användningen av ett avsnitt är som en länk till en dokumentationsfil.
<topic label="Någon konceptfil" href="concepts/some_file.html" />
Attributet href relaterar till det insticksprogram som manifestfilen tillhör. Om du behöver få åtkomst till en fil i ett annat insticksprogram kan du använda syntaxen
<topic label="avsnitt i ett annat insticksprogram" href="../other.plugin.id/concepts/some_other_file.html" />
2. Avsnitt som behållare
Den näst vanligaste användningen för ett avsnitt är att använda det som en behållare för
andra innehållsförteckningar. Själva behållaravsnittet kan även alltid hänvisa till en viss
fil.
<topic label="Integrerad utvecklingsmiljö" href="concepts/ciover.htm"
>
<topic label="Starta IDE" href="concepts/blah.htm"
/>
...
</topic>
Länkelementet
Länkelementet gör det möjligt att länka innehållsförteckningen som har definierats i en annan inehållsförteckningsfil. Alla avsnitt från innehållsförteckningsfilen som anges i innehållsförteckningsattributet visas i innehållsförteckningen som om de hade definierats direkt i stället för länkelementet. Om du vill inkludera innehållsförteckning från filen api.xml skriver du
<topic label="Referenser" >
...
<link toc="api.xml" />
...
</topic>
Ankarelementet
Med ankarelementet definieras en punkt som gör det möjligt att länka andra innehållsförteckningsfiler till navigeringen och utöka den utan att använda länkelementet och hänvisa till andra innehållsförteckningsfiler därifrån. Om du vill tillåta infogning av innehållsförteckning med flera avsnitt efter dokumentet "ZZZ" definierar du ett ankare på följande sätt:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Innehållsförteckningselementet
Innehållsförteckningselementet är en innehållsförteckning för gruppering av avsnitt och andra element som är definierade i den här filen. Med etiketten identifieras innehållsförteckningen för användaren när den visas för användaren. Det valfria avsnittsattributet är sökvägen till en avsnittsfil som beskriver innehållsförteckningen. det valfria link_to-attributet medger länkning av innehållsförteckning från den här filen till en annan innehållsförteckningsfil som finns högre upp i navigeringshierarkin. Värdet på attributet link_to måste ange ett ankare i en annan innehållsförteckningsfil. Om du vill länka innehållsförteckningen från myapi.xml till filen api.xml angiven i ett annat insticksprogram använder du syntaxen
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Mitt
verktygs-API"/>
...
<toc />
där tecknet # avgränsar innehållsförteckningens filnamn från ankaridentifieraren.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(sedan 3.1) ett valfritt element som möjliggör deklarering av i förväg byggda sökindex som skapas från dokument som tillhandahålls från insticksprogrammet.
index/
, nl/ja/JP/index/
, nl/en/US/index/
osv).(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="Hjälpsystemsexempel">
<topic label="Introduktion" href="intro.html"/>
<topic label="Uppgifter">
<topic label="Skapa ett projekt" href="tasks/task1.html">
<topic label="Skapa ett webbprojekt" href="tasks/task11.html"/>
<topic label="Skapa ett Java-projekt" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Testa ett projekt" href="tasks/taskn.html"/>
</topic>
<topic label="Exempel">
<topic label="Skapa Java-projekt" href="samples/sample1.html">
<topic label="Starta en guide" href="samples/sample11.html"/>
<topic label="Ställa in alternativ" href="samples/sample12.html"/>
<topic label="Slutföra skapandet av projekt" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(i filen tasks.xml)
<toc label="Bygga ett projekt">
<topic label="Bygga ett projekt" href="build/building.html">
<topic label="Bygga ett webbprojekt" href="build/web.html"/>
<topic label="Bygga ett Java-projekt" href="build/java.html"/>
</topic>
</toc>
(i filen samples.xml)
<toc link_to="maindocs.xml#samples" label="Använda kompileringsverktyget">
<topic label="Kompileringsexempel" href="compilesample/example.html">
<topic label="Steg 1" href="compilesample/step1.html"/>
<topic label="Steg 2" href="compilesample/step2.html"/>
<topic label="Steg 3" href="compilesample/step3.html"/>
<topic label="Steg 4" href="compilesample/step4.html"/>
</topic>
</toc>
Om vi antar att det finns fler dokument vars sökväg börjar med "samples" så visas de inte i navigeringsträden men är åtkomliga vid sökning. Det beror på attributet "extradir" i elementet <toc file="sample.xml" extradir="samples" /> i filen plugin.xml . Om du till exempel söker efter "Skapa Java-projekt" kan dokumentet "Andra sätt att skapa Java-projekt" returneras vars sökväg är samples/sample2.html.
Internationalisering Innehållsförteckningens XML-filer kan översättas och de resulterande kopiorna (med översatta etiketter) placeras i katalogen nl/<språk>/<land> eller nl/<språk>. <language> and <country> står för de språk- och landskoder med två tecken som används i språkmiljökoder. Översättningar till traditionell kinesiska placeras t.ex. i katalogen nl/zh/TW. Katalogen nl/<language>/<country> har högre prioritet än nl/<language>. Endast om ingen fil återfinns i nl/<language>/<country> används den fil som finns i nl/<language>. Rotkatalogen för ett insticksprogram genomsöks sist.
Dokumentationen i doc.zip kan du lokalisera genom att skapa
en doc.zip-fil med översatta versioner av dokumenten och placera doc.zip
i
katalogen nl/<language>/<country> eller nl/<language>. Hjälpsystemet söker efter filerna under dessa kataloger innan insticksprogrammets katalog används som standard.
Copyright (c) 2000, 2006 IBM Corporation and others.
All rights reserved. Detta program och medföljande material tillhandahålls under villkoren för Eclipse Public License v1.0 som medföljer denna distribution och finns tillgänglig på
http://www.eclipse.org/legal/epl-v10.html