Расположения сервера справки и файлов

Для предоставления конкретных 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"

ссылается на таблицу стилей в каталоге модуля текущего продукта.