Оглавление (TOC)

org.eclipse.help.toc

Предназначена для регистрации добавления электронной справки для отдельного модуля.

Каждый модуль, добавляющий справочные файлы, должен, в общем случае, выполнять следующие операции:

Также, модуль может предоставлять индекс для увеличения производительности во время первого поиска. Разрешается регистрировать только один индекс для каждого модуля - указание нескольких элементов 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>


<!ELEMENT index EMPTY>

<!ATTLIST index

path CDATA #REQUIRED>

(начиная с 3.1) необязательный элемент, позволяющий добавлять индекс для поиска по документам, предоставляемым этим модулем.



Ниже приведен пример использования точки расширения toc.

(в файле 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>. Справочная система выполнит поиск файлов в этих каталогах до того, как по умолчанию обратится к каталогу модуля.
 

Для использования этой точки расширения какой-либо дополнительный код не требуется. Достаточно предоставить соответствующие файлы манифеста, указанные в файле plugin.xml.

Реализация по умолчанию UI справочной системы, поставляемая в платформе Eclipse, полностью поддерживает точку расширения toc.