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.
Ein Dokumentations-Plug-in kann von einer JAR-Datei aus laufen, oder bei der Installation in ein Plug-in-Verzeichnis entpackt werden. Ein JAR für Plug-in-Archive 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.
Für Plug-ins, die nicht verpackt ausgeführt werden, kann die Dokumentation 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.
Beachten Sie, dass für Plug-ins, die von einer JAR-Datei aus ausgeführt werden, die Dokumentation nicht zusätzlich noch in doc.zip enthalten sein muss, und dass eine solche Installation von doc.zip in einem nicht entkomprimierten JAR von der Hilfefunktion nicht unterstützt wird.
Beim Auflösen von Dateinamen in einem Plug-in, das nicht verpackt ausgeführt wird, 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:
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.)
Zusätzlich zu den länderspezifischen Verzeichnissen überprüft das Hilfesystem bei der Lokalisierung von Hilferessourcen die Verzeichnisse der Fenstertechnik- und Betriebssysteme. Die Suche wird in der folgenden Reihenfolge durchgeführt: Unterverzeichnisse ws, os, nl, dann das Stammverzeichnis des Plug-ins, bis die Ressource gefunden wird. Dokumente und andere Ressourcen, wie z.B. Grafiken, die sich von System zu System unterscheiden, sollten in die Verzeichnisse 'ws' oder 'os' für bestimmte Plattformen gestellt 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.
Wie unter Produkt definieren beschrieben, werden Branding-Informationen häufig in ein Plug-in eingefügt, das ein Produkt beschreibt. Auf Hilferessourcen im Produkt-Plug-in kann vom Inhaltsverzeichnis oder von bestimmten Abschnitten aus über eine spezielle Kennung "PRODUCT_PLUGIN" für die Plug-in-ID verwiesen werden. Beispiel:
href="../PRODUKT_PLUGIN/book.css"
verweist auf ein Style-Sheet, das sich im Plug-in für das zurzeit aktive Produkt befindet.