Índice (TOC)

org.eclipse.help.toc

Permite registar uma contribuição de ajuda online para um plug-in individual.

Cada plug-in que contribui com ficheiros de ajuda deve, em geral, efectuar o seguinte:

Como opção, pode ser pré-construído e registado um índice de pesquisa utilizando o elemento index, para o desempenho da primeira tentativa de pesquisa. Só pode ser registado um índice por cada plug-in - vários elementos index irão provocar um comportamento indefinido.

<!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

category CDATA #IMPLIED>


<!ELEMENT index EMPTY>

<!ATTLIST index

path CDATA #REQUIRED>

(a partir da edição 3.1) um elemento opcional que permite a declaração de um índice de pesquisa pré-construído, criado a partir dos documentos contribuídos por este plug-in.



De seguida é apresentado um exemplo de como utilizar o ponto de extensão toc.

(no ficheiro plugin.xml)

 

<extension point=

"org.eclipse.help.toc"

>

<toc file=

"toc1.xml"

primary=

"true"

/>

<toc file=

"toc2.xml"

primary=

"true"

category=

"myCategory"

/>

<toc file=

"task.xml"

/>

<toc file=

"sample.xml"

extradir=

"samples"

/>

<index path=

"index/"

/>

</extension>

(no ficheiro maindocs.xml)

<toc label="Exemplo do Sistema de Ajuda">
 <topic label="Introdução" href="intro.html"/>
 <topic label="Tarefas">
  <topic label="Criar um Projecto" href="tasks/task1.html">
   <topic label="Criar um Projecto Web" href="tasks/task11.html"/>
   <topic label="Criar um Projecto Java" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testar um Projecto" href="tasks/taskn.html"/>
 </topic>
 <topic label="Exemplos">
  <topic label="Criar Projecto Java" href="samples/sample1.html">
   <topic label="Lançar um Assistente" href="samples/sample11.html"/>
   <topic label="Definir Opções" href="samples/sample12.html"/>
   <topic label="Terminar Criação de Projecto" href="samples/sample13.html"/>
  </topic>
  <anchor id="exemplos" />
 </topic>
</toc>


(no ficheiro tasks.xml)

<toc label="Construir um Projecto">
 <topic label="Construir um Projecto" href="build/building.html">
  <topic label="Construir um Projecto Java" href="build/web.html"/>
  <topic label="Construir um Projecto Java" href="build/java.html"/>
 </topic>
</toc>


(no ficheiro samples.xml)

<toc link_to="maindocs.xml#samples" label="Utilizar a Ferramenta de Compilação">
 <topic label="Exemplo da Ferramenta de Compilação" href="compilesample/example.html">
  <topic label="Passo 1" href="compilesample/step1.html"/>
  <topic label="Passo 2" href="compilesample/step2.html"/>
  <topic label="Passo 3" href="compilesample/step3.html"/>
  <topic label="Passo 4" href="compilesample/step4.html"/>
 </topic>
</toc>

Partindo do princípio que existem mais documentos cujo caminho começa por"exemplos", estes não serão apresentados na árvore de navegação, mas estarão acessíveis através da pesquisa.   Deve-se à presença do atributo "extradir" no elemento <toc file="sample.xml" extradir="samples" /> dentro do ficheiro plugin.xml . Por exemplo, pesquisar "Criar um Projecto Java" pode devolver um documento "Outras Formas de Criar um Projecto Java", cujo caminho é samples/sample2.html.

Internacionalização Os ficheiros XML TOC podem ser traduzidos e a cópia resultante (com etiquetas traduzíveis) deve ser colocada no directório nl/<idioma>/<país> ou nl/<idioma>.   <Idioma> e <país> representam códigos de idioma e país de duas letras, utilizados nos códigos de locale.   Por exemplo, as traduções de Chinês Tradicional devem ser colocadas no directório nl/zh/TW.   O directório nl/<idioma>/<país> possui uma prioridade mais elevada do que nl/<idioma>.  Se não for encontrado nenhum ficheiro no directório nl/<idioma>/<país>, será utilizado o ficheiro que reside em nl/<idioma>.   O directório raiz de um plugin será último a ser pesquisado.

A documentação contida num ficheiro doc.zip pode ser localizada criando um ficheiro doc.zip com a versão traduzida de documentos e colocando o doc.zip no directório
nl/<idioma>/<país> ou nl/<idioma>. O sistema de ajuda irá buscar ficheiros nos directórios antes de utilizar o directório predefinido do plugin.
 

Não é necessário nenhum código para utilizar este ponto de extensão. É apenas necessário facultar os ficheiros manifest adequados, mencionados no ficheiro plugin.xml.

A implementação predefinida da UI do sistema de ajuda, facultada com a plataforma Eclipse, suporta totalmente o ponto de extensão toc.