Каждый модуль, добавляющий справочные файлы, должен, в общем случае, выполнять следующие операции:
Также, модуль может предоставлять индекс для увеличения производительности во время первого поиска. Разрешается регистрировать только один индекс для каждого модуля - указание нескольких элементов index
приведет к неопределенному поведению.
<!ELEMENT extension (toc* , index?)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary (true | false) "false"
extradir CDATA #IMPLIED>
Описание конфигурации файла toc:
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!ELEMENT topic (topic | anchor | link )*
>
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED >
<!ELEMENT anchor EMPTY >
<!ATTLIST anchor id ID #REQUIRED >
<!ELEMENT link EMPTY >
<!ATTLIST link toc CDATA #REQUIRED >
В общем случае, модуль, который должен предоставить электронную справку, определит свои собственные файлы TOC. В итоге запуск справочной системы настраивается как определенный набор действий, и для выполнения этих действий можно использовать путь к файлу TOC.
Элемент topic
Все справочные элементы topic добавляются как часть элемента-контейнера toc. Они могут располагаться иерархически или в виде простого списка.
Элемент topic играет основную роль в структуре Оглавления. Элемент topic в основном применяется в следующих двух целях:
1. Предоставлять ссылку на файл документации - обычно это файл
HTML.
2. Играть роль контейнера для других элементов toc, в том же или
в другом файле манифеста.
1. Элементы topic как ссылки
Простейший вариант использования элемента topic - его применение в
качестве ссылки на файл документации.
<topic label="Файл с описанием" href="concepts/some_file.html" />
Атрибут href указывается относительно модуля, которому принадлежит файл манифеста. Если вам необходимо указать файл в другом модуле, воспользуйтесь следующим форматом:
<topic label="раздел в другом модуле" href="../other.plugin.id/concepts/some_other_file.html">
2. Элементы topic как контейнеры
Следующий по частоте вариант использования элемента topic - его
применение в качестве контейнера других элементов toc. Однако
элемент-контейнер topic может содержать ссылку и на конкретный файл.
<topic label="Интегрированная среда разработки" href="concepts/ciover.htm" >
<topic label="Запуск IDE" href="concepts/blah.htm" />
...
</topic>
Элемент link
Элемент link позволяет создать ссылку на Оглавление, определенное в другом файле toc. Все элементы topic из файла toc, указанного в атрибуте toc, будут показаны в Оглавлении точно так же, как если бы они были определены непосредственно на месте элемента link. Для того чтобы добавить элемент toc из файла api.xml, укажите, например:
<topic label="Ссылки" >
...
<link toc="api.xml" />
...
</topic>
Элемент anchor
Элемент anchor определяет точку, которая позволит связывать другие файлы toc с этой навигацией и расширять ее, не используя элемент link и не ссылаясь на другие файлы toc из этого места. Для того чтобы сделать возможной вставку Оглавления с дополнительными разделами после документа "ZZZ", определите элемент anchor следующим образом:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Элемент toc
Элемент toc - это Оглавление, в котором сгруппированы элементы topic и прочие элементы, определенные в этом файле. Элемент label указывает пользователю, какое Оглавление показано на экране. Необязательный атрибут topic - это путь к файлу topic с описанием TOC. Необязательный атрибут link_to позволяет связать toc из этого файла с другим файлом toc, расположенным выше в иерархии навигации. Значение атрибута link_to должно задавать элемент anchor в другом файле toc. Для того чтобы связать toc из myapi.xml с файлом api.xml, указанным в другом модуле, воспользуйтесь следующим форматом:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="API инструментов"/>
...
<toc />
где символ # отделяет имя файла toc от идентификатора anchor.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(начиная с 3.1) необязательный элемент, позволяющий добавлять индекс для поиска по документам, предоставляемым этим модулем.
index/
, nl/ja/JP/index/
, nl/en/US/index/
и т.д.).(в файле plugin.xml)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"maindocs.html"
primary=
"true"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(в файле maindocs.xml)
<toc label="Пример справочной системы">
<topic label="Введение" href="intro.html"/>
<topic label="Задачи">
<topic label="Создание проекта" href="tasks/task1.html">
<topic label="Создание Web-проекта" href="tasks/task11.html"/>
<topic label="Создание проекта Java" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Тестирование проекта" href="tasks/taskn.html"/>
</topic>
<topic label="Примеры">
<topic label="Создание проекта Java" href="samples/sample1.html">
<topic label="Запустить мастер" href="samples/sample11.html"/>
<topic label="Задать опции" href="samples/sample12.html"/>
<topic label="Закончить создание проекта" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(в файле tasks.xml)
<toc label="Компоновка проекта">
<topic label="Компоновка проекта" href="build/building.html">
<topic label="Компоновка Web-проекта" href="build/web.html"/>
<topic label="Компоновка проекта Java" href="build/java.html"/>
</topic>
</toc>
(в файле samples.xml)
<toc link_to="maindocs.xml#samples" label="Применение инструмента компиляции">
<topic label="Пример инструмента компиляции" href="compilesample/example.html">
<topic label="Шаг 1" href="compilesample/step1.html"/>
<topic label="Шаг 2" href="compilesample/step2.html"/>
<topic label="Шаг 3" href="compilesample/step3.html"/>
<topic label="Шаг 4" href="compilesample/step4.html"/>
</topic>
</toc>
Если в пути, начинающемся с "samples", существуют дополнительные документы, то они не будут показаны в дереве навигации, но будут доступны с помощью средств поиска. Это обусловлено наличием атрибута "extradir" в элементе <toc file="sample.xml" extradir="samples" /> внутри файла plugin.xml. Например, в результате поиска документа "Создание проекта Java" может быть возвращен документ "Другие способы создания проекта Java", находящегося в пути samples/sample2.html.
Экспорт строк XML-файлы TOC можно перевести на другие языки; полученную копию (с переведенными метками) следует поместить в каталог nl/<language>/<country> или nl/<language>. <language> и <country> обозначают двухбуквенные коды языка, используемые в кодах локалей. Например, перевод на китайский язык (КНР) следует поместить в каталог nl/zh/TW. Каталог nl/<language>/<country> имеет более высокий приоритет, чем каталог nl/<language>. Файл в nl/<language> используется только в том случае, если не найден файл в nl/<language>/<country>. Последним просматривается корневой каталог модуля.
Документацию, содержащуюся в doc.zip, можно перевести на нужный язык,
создав файл doc.zip с переведенными документами и поместив его в каталог
nl/<language>/<country> или nl/<language>. Справочная система
выполнит поиск файлов в этих каталогах до того, как по умолчанию обратится
к каталогу модуля.
Copyright (c) 2000, 2005 IBM Corporation и другие.
Все права защищены. Эта программа и сопутствующие материалы распространяются на условиях Eclipse Public License v1.0, поставляемой вместе с продуктом и доступной на Web-сайте
http://www.eclipse.org/legal/epl-v10.html