Cada plug-in que contribui com os arquivos de ajuda deve geralmente fazer o seguinte:
Opcionalmente, um índice de procura pode ser pré-construído e registrado utilizando o elemento index
para o desempenho da primeira tentativa de procura. Apenas um índice por plug-in pode ser registrado - vários elementos index
resultarão em 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>
Marcação de Configuração do Arquivo de Índice:
<!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 >
Geralmente, um plug-in que precisa fornecer ajuda online irá definir seus próprios arquivos TOC. 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 agir desse modo.
O elemento de tópico
Todos os elementos de 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 "burro de carga" da estrutura do Índice. Há 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 toc, 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 está relacionado ao plugin ao qual pertence o arquivo manifest. Se você precisar acessar um arquivo em um outro plugin, poderá utilizar a sintaxe
<topic label="topic in another 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 toc. 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="Starting the IDE" href="concepts/blah.htm"
/>
...
</tópicos>
O elemento de link
O elemento de link permite vincular 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 fossem definidos diretamente no lugar do elemento de link. Para incluir o arquivo toc pelo arquivo api.xml, você poderia gravar
<topic label="References" >
...
<link toc="api.xml" />
...
</tópicos>
O elemento anchor
O elemento anchor define um ponto que permitirá vincular outros arquivos toc a essa navegação, e estendê-lo, 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ê definiria uma âncora, como se 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 nesse arquivo. O rótulo identifica o índice para o usuário, quando este é exibido para o usuário. O atributo opcional topic é o caminho para um arquivo do tópico que descreve o arquivo de índice. O atributo opcional link_to permite vincular o arquivo de índice desse arquivo a outro arquivo de índice superior na hierarquia de navegação. O valor do atributo link_to deve especificar uma âncora em outro arquivo toc. Para vincular o arquivo de índice de myapi.xml para api.xml, especificado em outro plug-in, utilize a sintaxe
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
em que o caractere # separa o nome do arquivo toc do identificador anchor.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(desde o 3.1) um elemento opcional que permite a declaração de índice de procura pré-construído criado a partir de documentos contribuídos por esse plug-in.
index/
, nl/ja/JP/index/
, nl/en/US/index/
etc.).(no arquivo 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>
(no arquivo maindocs.xml)
<toc label="Help System Example">
<topic label="Introduction" href="intro.html"/>
<topic label="Tasks">
<topic label="Creating a Project" href="tasks/task1.html">
<topic label="Creating a Web Project" href="tasks/task11.html"/>
<topic label="Creating a Java Project" href="tasks/task12.html"/>
</tópico>
<link toc="task.xml" />
<topic label="Testing a Project" href="tasks/taskn.html"/>
</tópico>
<topic label="Samples">
<topic label="Creating Java Project" href="samples/sample1.html">
<topic label="Launch a Wizard" href="samples/sample11.html"/>
<topic label="Set Options" href="samples/sample12.html"/>
<topic label="Finish Creating Project" href="samples/sample13.html"/>
</tópico>
<anchor id="samples" />
</tópico>
</toc>
(no arquivo tasks.xml)
<toc label="Building a Project">
<topic label="Building a Project" href="build/building.html">
<topic label="Building a Web Project" href="build/web.html"/>
<topic label="Building a Java Project" href="build/java.html"/>
</tópico>
</toc>
(no arquivo samples.xml)
<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
<topic label="The Compile Tool Sample" href="compilesample/example.html">
<topic label="Step 1" href="compilesample/step1.html"/>
<topic label="Step 2" href="compilesample/step2.html"/>
<topic label="Step 3" href="compilesample/step3.html"/>
<topic label="Step 4" href="compilesample/step4.html"/>
</tópico>
</toc>
Supondo a existência de mais documentos com o caminho que começa com "samples", eles não serão exibidos na árvore de navegação, mas poderão ser acessados utilizando a pesquisa. Isso ocorre por causa da presença do atributo "extradir" no arquivo <toc file="sample.xml" extradir="samples" /> inside plugin.xml do elemento. Por exemplo, pesquisar "Criando Projeto Java" poderia retornar um documento "Outras Maneiras de Criação do Projeto Java", cujo caminho é samples/sample2.html.
Internacionalização Os arquivos XML de índice podem ser traduzidos e a cópia resultante (com rótulos traduzidos) deve ser colocada no diretório nl/<idioma>/<país> ou nl/<idioma>. <idioma> e <país> significam códigos de idioma e país de duas letras, conforme utilizado em códigos de localidade. Por exemplo, as traduções do chinês tradicional deverão ser colocadas no diretório nl/zh/TW. O diretório nl/<idioma>/<país> possui prioridade mais alta que o diretório nl/<idioma>. Apenas se nenhum arquivo for encontrado no diretório nl/<idioma>/<país>, o arquivo que reside no diretório nl/<idioma> será utilizado. O diretório raiz de um plugin será pesquisado por último.
A documentação contida no doc.zip pode ser localizada criando
um arquivo doc.zip com a versão traduzida de documentos e colocando 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.
Direitos Autorais (c) 2000, 2005 IBM Corporation e outros.
Todos os direitos reservados.
Este programa e os materiais que o acompanham são disponibilizados
sob os termos da Eclipse Public License v1.0 que acompanha esta
distribuição e estão disponíveis no endereço http://www.eclipse.org/legal/epl-v10.html