Hinweis: Die Entwicklung der Hilfefunktion ist noch nicht abgeschlossen. Vor dem Erreichen der Stabilität kann es daher zu Änderungen kommen. Die Hilfefunktion wird im vorliegenden Status zur Verfügung gestellt, um Rückmeldungen der ersten Anwender zu erhalten, und unter der Voraussetzung, dass Details des Ergänzungsmechanismus auf erhebliche Weise geändert werden könnten.

Ergänzungen

Kennung: org.eclipse.help.contributions

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

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

Konfigurationsbefehle für den Erweiterungspunkt contributions:

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> Konfigurationsbefehle für Themen (werden in die Manifestdatei für die Themen gestellt):

    <!ELEMENT topics (topic)* ) >
    <!ATTLIST topics id  ID #REQUIRED >

    <!ELEMENT topic (topic)* >
    <!ATTLIST topic id ID #IMPLIED >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href  CDATA #IMPLIED >

Konfigurationsbefehle für Informationssets (werden in die Manifestdatei für das Informationsset gestellt):

    <!ELEMENT infoset (infoview)*  >
    <!ATTLIST infoset  id  ID  #REQUIRED >
    <!ATTLIST infoset  label  CDATA  #REQUIRED >
    <!ATTLIST infoset  href  CDATA #IMPLIED >
    <!ATTLIST infoset  standalone  (false|true) false  #IMPLIED >

    <!ELEMENT infoview EMPTY>
    <!ATTLIST infoview id ID #REQUIRED >
    <!ATTLIST infoview label CDATA #IMPLIED >

Konfigurationsbefehle für Einfügeaktionen (werden in die Manifestdatei für die Aktionen gestellt):

    <!ELEMENT actions (insert)* >
    <!ATTLIST actions infoview CDATA #REQUIRED >
    <!ATTLIST actions standalone (true | false) false #IMPLIED >

    <!ELEMENT insert (insert) >
    <!ATTLIST insert from CDATA #REQUIRED >
    <!ATTLIST insert to CDATA #REQUIRED >
    <!ATTLIST insert as (child | first-child | last-child | prev-sib | next-sib) "child" >
    <!ATTLIST insert label CDATA #IMPLIED >

Ein Plug-in, das eine Onlinehilfefunktion zur Verfügung stellen soll, muss generell eigene Manifestdateien für Themen sowie Manifestdateien für die erforderlichen Aktionen definieren, mit denen die Themen in der korrekten Position eingebunden werden. Die Hilfefunktion wird letztlich so konfiguriert, dass sie bei bestimmten Aktionen gestartet wird. Hierzu kann die ID des Informationssets verwendet werden.

Es gibt vier Typen von XML-Elementen, die in einem Plug-in verwendet werden können: "topic" (Thema), "infoset" (Informationsset), "action" (Aktion) und "insert element" (Einfügeelement).

Element "topic" (Thema)

In Bezug auf die Elemente "topic" werden alle Themen als Teil des Themencontainerelements ergänzt. Sie können eine hierarchische Struktur aufweisen oder in einer unstrukturierten Liste aufgeführt sein. Ein Themenmanifest wird als Datenquelle für die Verzahnung mit anderen Themen und die Verwaltung in einem integrierten Netz mit unterschiedlichen Sichten betrachtet. Außerdem können über ihre ID Aktionen für Themen ausgeführt werden. Aktionen sind jedoch auch für Themengruppen möglich (hierzu muss die ID der übergeordneten Themen oder des entsprechenden Themenelements angegeben werden) Wenn später Themen in Sichten oder andere Themen eingebunden werden, wird die im Themenmanifest definierte Struktur verwaltet und unterliegt Änderungen, die durch Einfügeaktionen vorgenommen werden.

Das Element "topic" ist quasi das Zugpferd der Navigationsstruktur. Für dieses Element gibt es drei unterschiedliche Einsatzmöglichkeiten:

1.  Link zu einer Dokumentationsdatei (normalerweise eine HTML-Datei)
2.  Container für andere Themen, die entweder im gleichen Manifest oder in einem anderen Manifest angegeben sind
3.  Einfügemarke für andere Themen, 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="Some concept file" href="concepts/some_file.html" />

Das Attribut "href" ist auf das Plug-in bezogen, 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 Container
Die nächste gängige Verwendung eines Themas ist ein Container für andere Themen. 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>

3.  Themen als Einfügemarken
Themen können als Einfügemarken verwendet werden. Auf diese Weise stellen sie eine logische Position zur Verfügung, an der andere Themen zusammengeführt werden können. Ein Thema muss mit einer ID ausgestattet sein, wenn es als Einfügemarke verwendet werden soll.
 
 

Element "infoset" (Informationsset)

Ein Informationsset ist ein Eingangspunkt in ein Dokumentationsnetz. Es ist mit einer Objektgruppe aus Sichten vergleichbar.

Sichten dienen dazu, in einem Dokumentationsnetz semantische Gruppierungen auf einer allgemeinen Ebene bereitzustellen. Sie werden innerhalb eines Informationssets unter Verwendung des Elements infoview definiert. Ein Dokumentationsteam könnte über Sichten Abschnitte für erste Schritte, Tasks und Referenzinformationen (bzw. andere vom Produktteam definierte Sichten) erstellen. Die Plattform gibt die tatsächlichen Abschnitte nicht an, sondern nur den Mechanismus, mit dem sie definiert werden können.

Beispielsweise kann eine Tasksicht definiert werden, in der alle Themen zusammengeführt werden, die Vorgehensweisen beschreiben. Außerdem könnte eine zusätzliche Komponentensicht definiert werden, die eine Baumstruktur der Themen enthält und alle Komponenten sowie deren Dokumentation anzeigt.

Das Element "infoview" stellt einen Container für Themen dar, die von mehreren Plug-ins gemeinsam benutzt werden können. Es bietet einen Blick auf die gesamte Dokumentation. Es kann vorkommen, dass eine Reihe von unterschiedlichen Plug-ins Ergänzungen für dieselbe logische Dokumentationskomponente zur Verfügung stellen. Dieses Element stellt sicher, dass diese Komponenten in einer Komponentensicht kohärent zusammengeführt werden.

Element "actions" (Aktionen)

Das Aktionsmanifest enthält Aktionen zur Script-Erstellung, die für Themen und Sichten ausgeführt werden. Gegenwärtig ist nur eine einzige Aktion verfügbar. Es handelt sich um die Aktion "insert" (Einfügen), mit der Themen und Sichten in einem integrierten Informationsset, das mehrere Sichten verwendet, zusammen geschrieben werden können.

Die Aktionen sind Strukturaktionen (insert) und werden daher auf eine bestimmte Informationssicht angewendet. Alle Einfügeaktionen in einem Manifest erstellen daher die Themenhierarchie einer Informationssicht.

Element "insert" (Einfügen)

Die Erstellung einer integrierten Informationsstruktur mit einem ununterbrochenen Navigationsfluss ist einer der kompliziertesten Aspekte einer komponentenorientierten Navigation. Zu diesem Zweck wird ein Mechanismus benötigt, mit dem Sie Einfügemarken publizieren, die zu verwendende Einfügemarke auswählen sowie angeben können, wo Themen eingefügt werden sollen (parent, child, before, after).

Die Einfügemarken können Themen oder Sichten sein. Ein Thema kann dann als Einfügemarke verwendet werden, wenn es mit einer ID versehen ist. Sichten müssen immer über IDs verfügen. Nur vollständig qualifizierte IDs werden als Verweise verwendet. Die vollständig qualifizierte Themen-ID des Themas <topic id="concepts" label="concepts">  im Plug-in "org.eclipse.help.examples.ex1" lautet beispielsweise "org.eclipse.help.examples.ex1.concepts".

Da sich die Einfügemarken in der Regel in anderen Plug-ins befinden und diese Plug-ins unter Umständen nicht installiert sind, haben Sie die Möglichkeit, eine alternative Einfügemarke anzugeben. In der Standardeinstellung bleibt ein Thema in seine Komponentenhierarchie eingeordnet, wenn keine der angegebenen Einfügemarken erfolgreich verwendet werden kann. Mit dem Attribut "to" wird die Zieleinfügemarke angegeben. Das im Attribut "from" angegebene Thema ist das Thema, das eingefügt wird. Zum Einfügen eines Themas können die folgenden Methoden verwendet werden. Sie werden mit dem Attribut "as" angegeben:

Gegenwärtig kann ein Thema in einer Informationssicht (infoview) nur ein Mal eingefügt werden. Es kann jedoch in mehreren Informationssichten verwendet werden. Dies bedeutet, dass beim Einfügen eines übergeordneten Themas (und somit seiner untergeordneten Baumstruktur) in ein Informationsset keines seiner Kindelemente in derselben Informationssicht erneut eingefügt werden kann. Das Einfügen erstellt im Grunde genommen unteilbare Partitionen für eine spezifische Informationssicht.

Alternative Einfügeoptionen stehen zur Verfügung und können ausgeführt werden, wenn die zuvor angegebenen Aktionen nicht erfolgreich waren. Die verschachtelten Unterelemente "insert" des Elements "insert" stellen diese Alternativen zur Verfügung. Eigentlich handelt es sich hierbei um einen Zurücksetzungsmechanismus, der beim Fehlschlagen einer Einfügeaktion die verschachtelte Einfügeaktion ausführt. Wenn die erste Option für die Einfügemarke erfolgreich verwendet werden konnte, werden die anderen alternativen Einfügemarken ignoriert.
 

Beispiele:

Das folgende Beispiel verwendet den Erweiterungspunkt contributions. 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 Ergänzungsdateien besteht, auch durch eine andere Kombination aus Themen und Aktionsdateien erstellt werden könnte.)

Angaben in der Datei plugin.xml:
 

   <!-- Erweiterungspunkt für Hilfefunktionsergänzung verwenden, um Informationssets, Themen -->
   <!-- und Aktionsdateien zu definieren. Der Erweiterungspunkt wird zwei Mal verwendet,     -->
   <!-- nämlich zum Definieren des Informationssets und dessen Sicht sowie zum Definieren der   -->
   <!-- Themen und ihren zugeordneten Aktionen.                                         -->
   <extension point="org.eclipse.help.contributions">
    <infoset  name="infoset.xml"/>
   </extension>

   <extension point="org.eclipse.help.contributions">
     <topics  name="infosetTopics.xml"/>
     <actions name="infosetActions.xml"/>
   </extension>

   <!-- Hilfeergänzung für dieses Plug-in konfigurieren -->
   <!-- Diese Komponente sollte in einem Dokumentations-Plug-in sein -->
   <extension point="org.eclipse.help.contributions">
        <topics name="topics.xml"/>
        <actions name="topicsActions.xml" />
   </extension>
 
 

Angaben in der Datei infoset.xml:

<!-- Informationsset und alle verwendeten Sichten definieren. -->
<infoset id="ex1InfosetId" label="%help_system_example">
      <infoview id="topicsView" label="%topics"/>
</infoset>


Angaben in der Datei infosetTopics.xml:

<!-- Containerthema definieren, das die allgemeinen Themen enthält. Hierdurch -->
<!-- können alle allgemeinen Themen unter der Sicht im Informationsset     >
<!-- schneller und einfacher eingefügt werden.                                                                     -->
<topics id="topLevelTopics">
  <topic id="concepts" label="%concepts"/>
  <topic id="tasks" label="%tasks"/>
  <topic id="references" label="%references"/>
  <topic id="samples" label="%samples"/>
</topics>


Nun werden die Themen definiert, die in den oben angegebenen allgemeinen Themen enthalten sind.

Angaben in der Datei topics.xml:

<topics id="topics">
 <topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
 <topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
  <topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
  <topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
 </topic>
 <topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
 <topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>


Als Nächstes müssen die Einfügeaktionen definiert werden, die zur Erstellung der Dokumentationshierarchie benötigt werden.

Angaben in der Datei infosetActions.xml:

<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(Angaben in der Datei topicsActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.aConceptId"
   to="org.eclipse.help.examples.ex1.concepts" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aTaskId"
   to="org.eclipse.help.examples.ex1.tasks" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aReferenceId"
   to="org.eclipse.help.examples.ex1.references" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aSampleId"
   to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
 
 

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


 

Nicht integrierte Komponenten

Plug-ins können sowohl durch sich selbst als auch im Rahmen einer größeren Komponente oder eines umfangreicheren Produkts installiert werden. Bei einem eigenständigen Plug-in sollte sichergestellt werden, dass das Informationsset sichtbar ist. Sind die Themen in ein größeres Netz integriert, ist es wahrscheinlich nicht besonders sinnvoll, wenn das Buch weiterhin völlig eigenständig angezeigt wird. Um eine solche nicht oder nur wenig integrierte Dokumentation zu unterstützen, kann ein Plug-in ein Informationsset sowie zugeordnete Aktionen definieren und deren Attribut "standalone" auf "true" setzen. Durch diese Konfiguration werden Einfügeaktionen nur dann ausgeführt, wenn die entsprechenden Themen nicht an anderer Stelle ergänzt wurden, und das Informationsset wird nur dann angezeigt, wenn es nicht leer ist. Das Festlegen von Attributen "standalone" für Aktionen und Informationssets ist hilfreich, wenn ein Szenario für das Anzeigen aller verfügbaren Informationen realisiert werden soll, bei dem die Dokumentation nicht zu einem allgemein bekannten Informationsset hinzugefügt werden kann, die Dokumentation des Plug-ins jedoch trotzdem verfügbar sein und angezeigt werden soll.

Zeichenfolgen auslagern

Dateien "Plugin.xml" lagern ihre Zeichenfolgen aus, indem eine Zeichenfolge durch einen Schlüssel (z. B. %pluginName) ersetzt und dann in der Datei "plugin.properties" ein Eintrag mit dem folgenden Format erstellt wird:
    pluginName = "Beispiel-Plug-in für Onlinehilfefunktion"
Die XML-Dateien für Ergänzungen werden auf ähnliche Weise ausgelagert. Um beispielsweise <topic id="plainTasks" label="Vollständige Angaben"> auszulagern, ersetzen Sie die Bezeichnung durch den Schlüssel "%plainStuff". Das Thema sieht dann wie folgt aus:
    <topic id="plainTasks" label="%plainStuff">
Anschließend muss in der Datei "doc.properties" der folgende Eintrag erstellt werden:
    plainStuff = Vollständiger Inhalt
Die Hilfefunktion sucht in der Datei "doc.properties", wenn Zeichenfolgen durch eine Ergänzung für die Onlinehilfefunktion ausgelagert wurden.
 

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 optionale Standardimplementierung der Benutzerschnittstelle für die Hilfefunktion, die durch die Eclipse-Plattform bereitgestellt wird, unterstützt den Erweiterungspunkt contributions ohne Einschränkungen.

Copyright IBM Corp. 2000, 2001. Alle Rechte vorbehalten.