Descrição: para registrar uma contribuição de ajuda online para um plug-in individual.
Cada plug-in que contribui com os arquivos de ajuda deve geralmente fazer o seguinte:
<!ELEMENT toc EMPTY>
<!ATTLIST toc file CDATA #REQUIRED>
<!ATTLIST toc primary (true | false) "false">
<!ATTLIST toc extradir CDATA #IMPLIED>
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!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 >
Geralmente, um plug-in que precisa fornecer ajuda online irá definir seus próprios arquivos TOCs. Ao final, o sistema de ajuda é configurado para ser lançado como algumas ações e o caminho do arquivo TOC pode ser utilizado para fazer isso.
O elemento de tópico
Todos os elementos do tópico de ajuda são contribuídos como parte do elemento do contêiner de toc. Eles podem ter uma estrutura hierárquica, ou podem ser listados como uma lista simples.
O elemento de tópico é o "faz-tudo" da estrutura do Índice. Existem duas utilizações típicas para o elemento de tópico:
1. Fornecer um link para o arquivo de documentação - geralmente um arquivo HTML.
2. Agir como um contêiner para outros tocs, em um mesmo manifest ou
em outro.
1. Tópicos como links
A utilização mais simples do tópico é como um link para um arquivo de documentação.
<topic label="Some concept file" href="concepts/some_file.html" />
O atributo href é relacionado ao plug-in ao qual o arquivo manifest pertence. Se você precisar acessar um arquivo em um outro plug-in, é possível utilizar a sintaxe
<topic label="tópico em outro plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Tópicos são contêineres
A próxima utilização mais comum de um tópico é utilizá-lo como um contêiner
para outros tópicos. O tópico contêiner por si só pode sempre também se referir
a um arquivo em particular.
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Iniciando o IDE" href="concepts/blah.htm"
/>
...
</tópicos>
O elemento de link
O elemento de link permite estabelecer link com o Índice definido em outro arquivo toc. Todos os tópicos do arquivo toc especificado no atributo toc irão aparecer no índice, como se eles fossem definidos diretamente no lugar do elemento do link. Para incluir o toc do arquivo api.xml, você pode gravar
<topic label="Referências" >
...
<link toc="api.xml" />
...
</tópicos>
O elemento de âncora
O elemento de âncora define um ponto que permitirá estabelecer link com outros arquivos toc para esta navegação, e o estender, sem utilizar o elemento de link e fazer referência a outros arquivos toc a partir daqui. Para permitir inserir o Índice com mais tópicos após o documento "ZZZ", você irá definir uma âncora como segue:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
O elemento de toc
O elemento de toc é um Índice que agrupa tópicos e outros elementos definidos neste arquivo. O rótulo identifica o índice do usuário, quando ele for exibido para o usuário. O atributo link_to opcional permite estabelecer link de toc deste arquivo em outro arquivo toc que está sendo superior na hierarquia de navegação. O valor do atributo link_to deve especificar uma âncora em outro arquivo toc. Para estabelecer link de toc do arquivo myapi.xml para api.xml especificado em outro plugin, você irá utilizar a sintaxe
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
em que # caractere separa o nome do arquivo toc do identificador de âncora.
Exemplos:
A seguir encontra-se um exemplo de utilização do ponto de extensão toc. Assuma que o seguinte é para um plug-in com identificação nomeada "org.eclipse.help.examples.ex1". (O exemplo tende a ser uma amostra geral e deve ser observado que a mesma hierarquia de documentação, resultando de todos os arquivos toc a seguir, poderia também ser criada com combinação diferente de outros arquivos toc.)
(no arquivo plugin.xml)
<extension point="org.eclipse.help.toc">
<toc file="maindocs.xml" primary="true" />
<toc file="task.xml" />
<toc file="sample.xml" extradir="samples" />
</extension>
(no arquivo maindocs.xml)
<toc label="Exemplo de Sistema de Ajuda">
<topic label="Introdução" href="intro.html"/>
<topic label="Tarefas">
<topic label="Criando um Projeto" href="tasks/task1.html">
<topic label="Criando um Projeto da Web" href="tasks/task11.html"/>
<topic label="Criando um Projeto Java" href="tasks/task12.html"/>
</tópico>
<link toc="task.xml" />
<topic label="Testando um Projeto" href="tasks/taskn.html"/>
</tópico>
<topic label="Amostras">
<topic label="Criando Projeto 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="Concluir Projeto de Criação" href="samples/sample13.html"/>
</tópico>
<anchor id="samples" />
</tópico>
</toc>
(no arquivo tasks.xml)
<toc label="Construindo um Projeto">
<topic label="Construindo um Projeto" href="build/building.html">
<topic label="Construindo um Projeto da Web" href="build/web.html"/>
<topic label="Construindo um Projeto Java" href="build/java.html"/>
</tópico>
</toc>
(no arquivo samples.xml)
<toc link_to="maindocs.xml#samples" label="Utilizando a Ferramenta de Compilação">
<topic label="A Amostra de Ferramenta de Compilação" href="compilesample/example.html">
<topic label="Etapa 1" href="compilesample/step1.html"/>
<topic label="Etapa 2" href="compilesample/step2.html"/>
<topic label="Etapa 3" href="compilesample/step3.html"/>
<topic label="Etapa 4" href="compilesample/step4.html"/>
</tópico>
</toc>
Aqui está o resultado da hierarquia da documentação no Workbench do Eclipse:
Ao assumir que mais documentos existem com o caminho que começa com "samples", eles não serão exibidos na árvore de navegação, mas serão acessíveis utilizando a pesquisa. Isso ocorre devido a presença do atributo "extradir" no arquivo <toc file="sample.xml" extradir="samples" /> inside plugin.xml do elemento. Por exemplo, procurar "Criando Projeto Java" poderia retornar um documento "Outras Maneiras de Criação do Projeto Java", cujo caminho é samples/sample2.html.
Os documentos contidos em doc.zip podem ser localizados através da criação
de um arquivo doc.zip com versão convertida de documentos e através da colocação de doc.zip
no diretório
nl/<idioma>/<país> ou nl/<idioma>. O sistema de ajuda
procurará os arquivos nesses diretórios antes de padronizar
o diretório de plug-in.
Informações de API: nenhum código é solicitado para utilização desse ponto de extensão. Tudo isso é necessário para alimentar os arquivos manifests apropriados no arquivoplugin.xml.
Implementação Fornecida: A implementação padrão do sistema de ajuda da UI fornecido com a plataforma Eclipse suporta completamente o ponto de extensão toc.