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>
Marcação de Configuração para ficheiro 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 >
Em geral, um plug-in que necessite de facultar ajuda online irá definir os seus próprios ficheiros TOC. No final, o sistema de ajuda está configurado para ser iniciado quando nele se possam utilizar algumas acções e o caminho do ficheiro TOC.
O elemento topic
Todos os elementos topic de ajuda contribuídos como parte de um elemento contentor toc. Podem ter uma estrutura hierárquica ou podem ser enumerados numa lista plana.
O elemento topic é a base da estrutura do Índice. Existem duas formas de utilizar o elemento topic:
1. Facultar uma ligação a um ficheiro de documentação - normalmente um ficheiro HTML.
2. Actuar como um contentor de outros elementos toc, no mesmo
ficheiro de manifesto ou noutros.
1. Tópicos como ligações
A utilização mais simples de um tópico é como uma ligação a um ficheiro de documentação.
<topic label="Ficheiro de algum conceito" href="concepts/some_file.html" />
O atributo href é relativo ao plug-in ao qual pertence o ficheiro manifest. Caso necessite de aceder a um ficheiro noutro plug-in, pode utilizar a sintaxe
<topic label="tópico noutro plug-in" href="../other.plugin.id/concepts/some_other_file.html"/>
2. Tópicos como contentores
A outra utilização mais comum de um tópico é como um contentor de outros toc. O próprio tópico contentor pode também fazer sempre referência a um ficheiro específico.
<topic label="Ambiente de Desenvolvimento Integrado" href="concepts/ciover.htm" >
<topic label="Iniciar o IDE" href="concepts/blah.htm"/>
...
</topic>
O elemento link
O elemento link permite ligar o Índice definido noutro ficheiro toc. Todos os tópicos do ficheiro toc especificado no atributo toc irão aparecer no índice como se tivessem sido definidos directamente no lugar do elemento link. Para incluir toc de um ficheiro api.xml, o utilizador pode escrever
<topic label="Referências" >
...
<link toc="api.xml" />
...
</topic>
O elemento anchor
O elemento anchor (âncora) define um ponto que irá permitir ligar outros ficheiros toc a esta navegação e expandi-la, sem utilizar o elemento link e referenciar outros ficheiros toc a partir deste local. Para permitir inserir um Índice com mais tópicos após o documento "ZZZ", o utilizador teria de definir um elemento anchor da seguinte forma:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
O elemento toc
O elemento toc é um Índice que agrupa tópicos e outros elementos definidos neste ficheiro. A etiqueta identifica o índice junto do utilizador, quando esta lhe é apresentada. O atributo topic adicional é o caminho para um ficheiro de tópicos que descreve o TOC. O atributo link_to opcional permite ligar toc deste ficheiro a outro ficheiro toc, numa posição mais elevada da hierarquia de navegação. O valor do atributo link_to tem de especificar uma âncora noutro ficheiro toc. Para ligar elemento toc de myapi.xml ao ficheiro api.xml, especificado noutro plugin, teria de utilizar a seguinte sintaxe
<toc link_to="../anotherPlugin/api.xml#moreapi" label="A Minha API de Ferramentas"/>
...
<toc />
em que o carácter # separa o nome do ficheiro toc do identificador de âncora.
<!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.
index/
, nl/ja/JP/index/
, nl/en/US/index/
etc.).(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.
Copyright (c) 2000, 2006 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais que o acompanham estão disponíveis sob os termos da Eclipse Public License v1.0, que acompanha esta distribuição e estão disponíveis em http://www.eclipse.org/legal/epl-v10.html