Ein Plug-in, das Hilfedateien ergänzt, sollte im Allgemeinen Folgendes ausführen:
Optional kann ein Suchindex vordefiniert und registriert werden mit Hilfe des Elements Index
, um den ersten Suchversuch durchzuführen. Es kann nur ein Index pro Plug-in registriert werden - mehrere Index
-Elemente führen zu einem undefinierten Verhalten.
<!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>
Konfigurationsbefehle für TOC-Datei:
<!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 >
Ein Plug-in, das ein Onlinehilfesystem zur Verfügung stellen soll, muss eigene TOC-Dateien für Inhaltsverzeichnisse definieren. Die Hilfefunktion wird letztlich so konfiguriert, dass sie bei bestimmten Aktionen gestartet wird. Hierzu kann der Pfad der TOC-Datei verwendet werden.
Element "topic" (Thema)
Alle Themenelemente der Hilfe werden im Rahmen des Containerelements für Inhaltsverzeichnisse ergänzt. Sie können eine hierarchische Struktur aufweisen oder in einer unstrukturierten Liste aufgeführt sein.
Das Element "topic" ist quasi das Zugpferd der Struktur des Inhaltsverzeichnisses. Für dieses Element gibt es zwei unterschiedliche Einsatzmöglichkeiten:
1. Link zu einer Dokumentationsdatei (normalerweise eine
HTML-Datei) bereitstellen.
2. Container für andere Inhaltsverzeichnisse, die entweder im gleichen
Manifest oder in einem anderen Manifest angegeben sind.
1. Themen als Links
Die einfachste Verwendung eines Themas ist ein Link zu einer
Dokumentationsdatei.
<topic label="Irgendeine Konzeptdatei" href="concepts/some_file.html" />
Das Attribut "href" bezieht sich auf das Plug-in, zu dem die Manifestdatei gehört. Wenn Sie auf eine Datei in einem anderen Plug-in zugreifen müssen, können Sie die folgende Syntax verwenden:
<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Themen als Containers
Die nächste gängige Verwendung eines Themas ist ein Container für
andere Inhaltsverzeichnisse. Das Containerthema selbst kann zusätzlich immer
auch selbst auf eine bestimmte Datei verweisen.
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="IDE starten" href="concepts/blah.htm" />
...
</topic>
Element "link" (Verbinden)
Das Link-Element ermöglicht das Verlinken eines Inhaltsverzeichnis, das in einer anderen toc-Datei definiert ist. Alle im "toc"-Attribut angegebenen Themen aus der "toc"-Datei werden im Inhaltsverzeichnis angezeigt, als ob sie direkt an Stelle des Elements "link" definiert worden wären. Zur Aufnahme der Datei 'toc' aus der Datei 'api.xml'können Sie Folgendes schreiben:
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
Element "anchor" (Verankern)
Das Element "anchor" definiert einen Punkt, der das Verlinken anderer "toc"-Dateien mit dieser Navigation sowie deren Erweiterung ermöglicht, ohne dabei das Element "link" zu verwenden und von hier aus auf andere "toc"-Dateien zu verweisen. Um das Einfügen von Inhaltsverzeichnissen mit weiteren Themen nach dem Dokument "ZZZ" zu ermöglichen, müssten Sie ein Element "anchor" wie folgt definieren:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Element "toc" (Inhaltsverzeichnis)
Das Element 'toc' ist ein Inhaltsverzeichnis, das Themen und andere Elemente, die in dieser Datei definiert sind, gruppiert. Die Bezeichnung gibt das Inhaltsverzeichnis für den Benutzer an, wenn es für den Benutzer angezeigt wird. Das optionale Attribut 'topic' ist der Pfad zu einer Thema-Datei, die die Datei TOC beschreibt. Das optionale Attribut 'link_to' ermöglicht das Verlinken des Elements "toc" aus dieser Datei mit einer anderen "toc"-Datei, die höher in der Navigationshierarchie platziert ist. Der Wert des Attributs 'link_to' muss ein Element 'anchor' in einer anderen Datei 'toc' angeben. Um ein Element "toc" aus der Datei "myapi.xml" mit einer in einem anderen Plug-in angegebenen Datei "api.xml" zu verbinden, würden Sie folgende Syntax verwenden:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Meine Tool-API"/>
...
<toc />
Hierbei trennt das Zeichen # den Namen der "toc"-Datei von der Kennung des Elements "anchor".
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Ab 3.1) Ein optionales Element, das die Deklaration eines vordefinierten Suchindex ermöglicht, der aus Dokumenten erstellt wurde, die durch dieses Plug-in beigesteuert wurden .
index/
, nl/ja/JP/index/
, nl/en/US/index/
etc.).Angaben in der Datei plugin.xml:
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"maindocs.html"
primary=
"true"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(Angaben in der Datei 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>
(Angaben in der Datei 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>
(Angaben in der Datei 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>
Wenn es mehrere Dokumente mit einem Pfad beginnend mit "samples" gibt, werden diese nicht im Navigationsbaum angezeigt, sind jedoch über die Suche zugreifbar. Das liegt am Attribut "extradir" im Element <toc file="sample.xml" extradir="samples" /> inside plugin.xml file. Die Suche etwa nach "Creating Java Project" könnte ein Dokument namens "Other Ways of Creating Java Project" liefern, dessen Pfad samples/sample2.html. lautet.
Internationalisierung Die Dateien 'TOC XML' können übersetzt werden und die daraus resultierende Kopie (mit übersetzten Bezeichnungen)sollte in dem Verzeichnis nl/<language>/<country> oder nl/<language> abgelegt werden. Die Codes <language> and <country> stand for two letter language and country codes as used in locale codes. Zum Beispiel sollten Übersetzungen in traditionellem Chinesisch in dem Verzeichnis nl/zh/TW abgelegt werden. Das Verzeichnis nl/<language>/<country> hat eine höhere Priorität als das Verzeichnis nl/<language>. Nur wenn keine Datei in dem Verzeichnis nl/<language>/<country> gefunden wird, wird die Datei verwendet, die in dem Verzeichnis nl/<language> abgelegt ist. Das Stammverzeichnis eines Plug-Ins wird zuletzt gesucht.
Die in doc.zip enthaltene Dokumentation kann durch Erstellen der Datei
doc.zip mit den übersetzten Versionen von Dokumenten und durch Stellen
von doc.zip in das Verzeichnis
nl/<sprache>/<land>
oder nl/<sprache> lokalisiert werden. Die Hilfefunktion sucht nach Dateien in diesem Verzeichnis, bevor
das Standardverzeichnis plugin durchsucht wird.
Copyright (c) 2000, 2005 IBM Corporation und Andere.
Alle Rechte vorbehalten. Dieses Programm und sein Begleitmaterial werden gemäß den Bedingungen der "Eclipse Public License v1.0" zur Verfügung gestellt, die dieser Lieferung beiliegt und unter
http://www.eclipse.org/legal/epl-v10.html abgerufen werden kann.