Для предоставления конкретных Web-страниц документации модуля в платформе предусмотрен собственный сервер документации. Отдельный сервер позволяет обрабатывать содержимое HTML независимо от браузера, а также обеспечить поддержку модулей. Для разработчиков модулей главное отличие заключается в большей гибкости при выборе способа структуризации файлов и указания ссылок.
Модуль документации можно запускать непосредственно из JAR или распаковав его в каталог модулей во время установки. Архив Jar не разворачивается в каталоге модуля, если в манифесте комплекта в атрибуте unpack
элемента plugin
указано значение true. В таком
модуле документация хранится в сжатом виде в файле jar модуля вместе с остальными файлами
модуля.
В распакованных модулях документация может поставляться в файле zip. Такой подход позволяет избежать неполадок, связанных с большим числом файлов, расположенных в каталоге модуля. В рассматриваемом примере модуля создается подкаталог html. При необходимости файлы html можно добавить в файл doc.zip. Структура содержимого этого файла zip должна соответствовать структуре файлов в каталоге модуля. В данном случае в его состав должен входить подкаталог html и все его содержимое.
Для модулей, запускаемых из JAR, размещение документации в файле doc.zip не требуется. Справочная система не поддерживает настройку файла doc.zip в неразвернутом файле jar модуля.
В процессе преобразования имен файлов в распасованных модулях сервер справки перед обращением к каталогу модуля просматривает содержимое файла doc.zip. Если аргумент, указанный в теге href, применяется в качестве ссылки, он должен быть указан относительно текущего модуля. Обратите внимание на следующую ссылку:
<topic label="Ref1" href="html/ref/ref1.html"/>
Модуль справки выполняет поиск этого файла следующим образом:
Для обращения к информации из Internet следует указать полную ссылку.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
Справочная система платформы для поиска каталога национального языка применяет схему, используемую для поиска других переведенных файлов. (Описание этой структуры каталогов приведено в разделе Файлы локали). Если применяется файл doc.zip, то файл doc.zip следует создать для каждой локали и разместить его в соответствующем каталоге локали. (В файле doc.zip не следует копировать структуру каталогов локали nl).
Кроме того, поиск ресурсов справки производится в каталогах оконной и операционной системы. Порядок следующий: подкаталоги ws, os, nl, корневой каталог модуля. Документы и другие ресурсы, такие как изображения, зависящие от платформы, должны размещаться в соответствующих каталогах ws (оконная система) и os (операционная система).
В аргументе href при необходимости можно указать ссылку на содержимое другого модуля. Для этого применяется нотации перекрестных ссылок на модули, обрабатываемые сервером справки:
<topic label="Ref1" href="../"another_plugin_id"/ref/ref1.html"/>
Например, следующий раздел позволяет указать ссылку на эту главу руководства программиста:
<topic label="Help Chapter in Platform Doc" href="../org.eclipse.platform.doc.isv/guide/help.html"/>
Примечание: Для упоминания содержимого из другого модуля следует применять ИД модуля, указанный в файле plugin.xml , а не имя каталога. Несмотря на то, что зачастую они совпадают, важно убедиться, что применяется именно ИД, а не имя каталога.
Информация о продукте часто располагается в модуле, определяющем продукт (см. Определение продукта). Ссылки на ресурсы модуля продукта можно задавать с помощью специального идентификатора "PRODUCT_PLUGIN". Например,
href="../PRODUCT_PLUGIN/book.css"
ссылается на таблицу стилей в каталоге модуля текущего продукта.