Inhaltsverzeichnis

Kennung: org.eclipse.help.toc

Beschreibung: An diesem Erweiterungspunkt kann eine Ergänzung für das Onlinehilfesystem eines einzelnen Plug-ins registriert werden.

Ein Plug-in, das Hilfedateien ergänzt, sollte im Allgemeinen Folgendes ausführen:

Konfigurationsbefehle für den Erweiterungspunkt toc (werden in die Datei plugin.xml gestellt):

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

Konfigurationsbefehle für Inhaltsverzeichnis (werden in die TOC-Datei gestellt):

    <!ELEMENT toc (topic | anchor | link)* >
    <!ATTLIST toc link_to CDATA #IMPLIED >
    <!ATTLIST toc label CDATA #REQUIRED >

    <!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)

Mit dem Element "link" können in einer anderen "toc"-Datei definierte Inhaltsverzeichnisse verbunden werden. 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. Um "toc" aus der Datei "api.xml" aufzunehmen, könnten Sie Folgendes schreiben:

<topic label="Referenzen" >
  ...
  <link toc="api.xml" />
  ...
</topic>

Element "anchor" (Verankern)

Das Element "anchor" definiert einen Punkt, der das Verbinden 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 in dieser Datei definierte Elemente zusammenfasst. Die Bezeichnung identifiziert das Inhaltsverzeichnis für den Benutzer, wenn sie diesem angezeigt wird. Das optionale Attribut "link_to" ermöglicht das Verbinden 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 "toc"-Datei 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".

Beispiele:

Das folgende Beispiel verwendet den Erweiterungspunkt toc. Ausgegangen wird von der Bereitstellung für ein Plug-in mit der ID org.eclipse.help.examples.ex1. (Das Beispiel ist als allgemeines Beispiel gedacht. Es ist daher zu beachten, dass die gleiche Dokumentationshierarchie, die aus allen folgenden toc-Dateien für Inhaltsverzeichnisse besteht, auch durch eine unterschiedliche Kombination aus anderen toc-Dateien erstellt werden könnte.)

Angaben in der Datei plugin.xml:

 <extension point="org.eclipse.help.toc">
  <toc file="maindocs.xml" primary="true" />
  <toc file="task.xml" />
  <toc file="sample.xml" extradir="samples" />
 </extension>
 

(in file maindocs.xml)

<toc label="Hilfesystem - Beispiel">
 <topic label="Einführung" href="intro.html"/>
 <topic label="Aufgaben">
  <topic label="Ein Projekt erstellen" href="tasks/task1.html">
   <topic label="Ein Webprojekt erstellen" href="tasks/task11.html"/>
   <topic label="Ein Java-Projekt erstellen" href="build/java.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Ein Projekt testen" href="tasks/taskn.html"/>
 </topic>
 <topic label="Beispiele">
  <topic label="Ein Java-Projekt erstellen" href="samples/sample1.html">
   <topic label="Einen Assistenten starten" href="samples/sample11.html"/>
   <topic label="Optionen angeben" href="samples/sample12.html"/>
   <topic label="Erstellung eines Projekts anschließen" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(Angaben in der Datei tasks.xml)

<toc label="Ein Projekt erstellen">
 <topic label="Ein Projekt erstellen" href="build/building.html">
  <topic label="Ein Webprojekt erstellen" href="build/web.html"/>
  <topic label="Ein Java-Projekt erstellen" href="build/java.html"/>
 </topic>
</toc>


(Angaben in der Datei samples.xml)

<toc link_to="maindocs.xml#samples" label="Das Kompiliertool verwenden">
 <topic label="Das Kompiliertool - Beispiel" href="compilesample/example.html">
  <topic label="Schritt 1" href="compilesample/step1.html"/>
  <topic label="Schritt 2" href="compilesample/step2.html"/>
  <topic label="Schritt 3" href="compilesample/step3.html"/>
  <topic label="Schritt 4" href="compilesample/step4.html"/>
 </topic>
</toc>


Auf diese Weise wird in der Eclipse-Workbench die folgende Dokumentationshierarchie erzeugt:

Help Sample

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 -Datei. Die Suche etwa nach "Erstellen eines Java-Projekts" könnte ein Dokument namens "Andere Möglichkeiten zur Erstellung eines Java-Projekts" liefern, dessen Pfad samples/sample2.html. lautet.

Internationalisierung

Die TOC XML-Dateien können übersetzt werden und die resultierende Kopie (mit übersetzten Kennsätzen) müssen in das Verzeichnis nl/<sprache>/<land> oder nl/<sprache> gestellt werden. Hierbei steht nl/<sprache>/<land> für den aus zwei Buchstaben bestehenden Code für Land und Sprache, wie in den Codes für Ländereinstellungen verwendet. Beispielsweise müssen die Übersetzungen für Traditionelles Chinesisch in das Verzeichnis nl/zh/TW gestellt werden. Das Verzeichnis nl/<sprache>/<land> hat eine höhere Priorität als nl/<sprache> Nur dann, wenn keine Datei in nl/<sprache>/<land> gefunden wird, wird die in nl/<sprache> vorhandenen Datei verwendet. Das Stammverzeichnis eines Plug-Ins wird zuletzt durchsucht.

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. Das Hilfesystem sucht nach Dateien in diesem Verzeichnis, bevor das Standardverzeichnis plugin durchsucht wird.
 

API-Informationen: Zur Verwendung dieses Erweiterungspunkts ist kein Code erforderlich. Sie müssen lediglich die entsprechenden Manifestdateien bereitstellen, die in der Datei plugin.xml angegeben sind.
 

Bereitgestellte Implementierung: Die Standardimplementierung der Benutzerschnittstelle für die Hilfefunktion, die durch die Eclipse-Plattform bereitgestellt wird, unterstützt den Erweiterungspunkt toc ohne Einschränkungen.


Copyright IBM Corp. und Andere 2000, 2002. Alle Rechte vorbehalten.