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. |
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:
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!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:
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">(Angaben in der Datei topicsActions.xml)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">Auf diese Weise wird in der Eclipse-Workbench die folgende Dokumentationshierarchie erzeugt:
<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>
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.