Die Plattform setzt einen eigenen Dokumentationsserver ein, um die tatsächlichen Webseiten für die Dokumentation des Plug-ins bereitzustellen. Durch einen angepassten Server kann die Plattform HTML-Inhalt browserunabhängig verarbeiten und eine Unterstützung dafür bereitstellen, dass dies vom Plug-in zur Kenntnis genommen wird. Der Hauptunterschied bei der Entwicklung eines Plug-ins liegt darin, dass Sie bei der Strukturierung der Dateien und der Angabe von Links etwas flexibler sind.
Die Dokumentation kann in Form einer komprimierten Datei (ZIP) geliefert werden, was Probleme verhindert, die entstehen können, wenn eine große Anzahl von Dateien im Plug-in Verzeichnis vorhanden ist. Im Beispiel-Plug-in haben Sie ein Unterverzeichnis namens html erstellt. Alternativ hätten Sie die HTML-Dateien auch in eine komprimierte Datei namens doc.zip stellen können. Diese komprimierte Datei muss die Dateistruktur unterhalb des Plug-in-Verzeichnisses nachahmen. Im Beispiel muss sie das Unterverzeichnis html und den gesamten Inhalt unterhalb von html enthalten.
Beim Auflösen von Dateinamen sucht der Hilfeserver in der Datei doc.zip nach Dokumenten, bevor das Plug-in-Verzeichnis selbst durchsucht wird. Bei einer Verwendung als Link wird davon ausgegangen, dass sich das Argument in einem Wert href auf das aktuelle Plug-in bezieht. Berücksichtigen Sie den folgenden Link:
<topic label="Ref1" href="html/ref/ref1.html"/>
Das Hilfe-Plug-in sucht wie folgt nach dieser Datei:
Seit dem Release 3.0 kann das gesamte Plug-in in komprimiertem Format installiert und direkt aus einem JARheraus ausgeführt werden. Ein JAR für Plug-in-Installationen wird nicht in ein Plug-in-Verzeichnis entkomprimiert, wenn der Wert des Attributs entpacken
des Elements Plug-in
im Featuremanifest auf 'true' gesetzt ist. In einem solchen Plug-in wird die Dokumentation zusammen mit den anderen Plug-in-Dateien in die JAR-Datei des Plug-ins komprimiert. Die Dokumentation muss nicht zusätzlich noch in doc.zip enthalten sein, und eine solche Installation von doc.zip in einem nicht entkomprimierten JAR wird von der Hilfefunktion nicht unterstützt.
Ein vollständig qualifizierter Link kann sich auf einen beliebigen Inhalt im Web beziehen.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
Die Hilfefunktion der Plattform verwendet das gleiche Suchschema für das Landessprachenverzeichnis wie der Rest der Plattform, um nach übersetzten Dateien zu suchen. (Eine Erläuterung dieser Verzeichnisstruktur finden Sie unter Spezifische Dateien für Ländereinstellung.) Bei Verwendung einer Datei doc.zip sollten Sie eine Datei doc.zip für jede Ländereinstellung erstellen und diese in das korrekte Verzeichnis für die Ländereinstellung stellen. (Die Verzeichnisstruktur für Ländereinstellungen - nl - sollte in der Datei doc.zip nicht repliziert werden.)
Das Argument href kann sich auch auf Inhalt in einem anderen Plug-in beziehen. Dies wird durch eine besondere Querverweisnotation für Plug-ins ermöglicht, die durch den Hilfeserver aufgelöst wird:
<topic label="Ref1" href="../"another_plugin_id"/ref/ref1.html"/>
Beispielsweise könnten Sie unter Verwendung des folgenden Abschnitts einen Link zum vorliegenden Kapitel des Programmiererhandbuchs herstellen:
<topic label="Help Chapter in Platform Doc" href="../org.eclipse.platform.doc.isv/guide/help.html"/>
Hinweis: Wenn Sie auf Inhalt in einem anderen Plug-in verweisen, müssen Sie unbedingt die ID des Plug-ins, die in seiner Datei plugin.xml deklariert ist, verwenden und dürfen nicht den Verzeichnisnamen angeben. In der Praxis sind diese Angaben zwar häufig identisch, aber Sie sollten auf alle Fälle prüfen, dass nicht der Verzeichnisname, sondern die ID verwendet wird.