Servidor de ajuda e localizações dos ficheiros

A plataforma utiliza o seu próprio servidor de documentação para fornecer as páginas Web reais à documentação do plug-in.  Um servidor personalizado permite à plataforma tratar conteúdo HTML de forma independente de browser e facultar suporte orientado para plug-ins.  A principal diferença para programadores de plug-ins é dispor de mais flexibilidade no modo de estruturar ficheiros e especificar ligações.

Um plug-in de documentação pode ser executado a partir de um ficheiro JAR ou desempacotado no directório plug-in durante a instalação. O JAR de arquivo de plug-in não é expandido num directório de plug-ins quando o valor do atributo unpack do elemento plugin estiver especificado como true no manifesto da função. Em tal plug-in, a documentação é compressa no JAR do plug-in, junto com outros ficheiros de plug-in.

Em plug-ins que sejam executados fora de pacotes, a documentação pode ser entregue num ficheiro zip, evitando assim problemas resultantes da presença de muitos ficheiros num directório de plug-in. No nosso plug-in exemplo, criámos um subdirectório chamado html.  Em alternativa, poderíamos ter colocado os nossos ficheiros html num ficheiro zip denominado doc.zip. Este ficheiro zip deve imitar a estrutura de ficheiros abaixo do directório do plug-in.  No nosso caso, deve conter o subdirectório html e todo o conteúdo abaixo de html.

Repare que para plug-ins executados a partir de um ficheiro JAR, não é preciso que a documentação esteja adicionalmente contida em doc.zip, e tal configuração de doc.zip num JAR de plug-ins compactado não é suportada pelo sistema de ajuda

Ao resolver nomes de ficheiros num plug-in executado fora de pacotes, o sistema de ajuda busca em doc.zip por documentos antes de buscar no directório de plug-in propriamente dito.  Quando utilizado como ligação, parte-se do princípio de que o argumento num tag href é relativo ao actual plug-in.  Considere a seguinte ligação:

   <topic label="Ref1" href="html/ref/ref1.html"/>

O plug-in de ajuda irá buscar por este ficheiro como se segue:

Pode ser utilizada uma ligação totalmente qualificada para remeter para qualquer conteúdo na Web.  

   <topic label="Ref1" href="http://www.exemplo.com/aMinhaReferência.html"/>

Idiomas nacionais e documentação traduzida

O sistema de ajuda da plataforma utiliza o mesmo esquema de busca de directórios de idiomas nacionais que o resto da plataforma para localizar ficheiros traduzidos.   (Consulte Ficheiros específicos de locale para uma explicação desta estrutura de directórios) .  Se utilizar um ficheiro doc.zip, deve compor um ficheiro doc.zip para cada locale e colocá-lo no directório do locale correcto.   (Não deve replicar a estrutura de directórios do locale nl dentro do ficheiro doc.zip.)

Além dos directórios específicos de locale, o sistema de ajuda verifica os directórios do sistema de janelas e do sistema operativo aquando da localização de recursos de ajuda. A busca realiza-se pela ordem seguinte: subdirectórios ws, os, nl, depois a raiz do plug-in, até localizar o recurso. Os documento e outros recursos como, por exemplo, imagens que difiram entre sistemas, devem ser colocados nos directórios ws ou os da plataforma específica.

Referências cruzadas a plug-ins

O argumento href também podem remeter para conteúdo de outro plug-in. Tal processa-se através de uma notação especial de referências cruzadas a plug-ins que é resolvida pelo servidor de ajuda:

   <topic label="Ref1"
href="PLUGINS_ROOT/another_plugin_id/ref/ref1.html"/>

Aqui, o PLUGINS_ROOT será processado em tempo de execução e substituído pelo directório de raiz para plug-ins. Pode especificar o seu id de plug-ins para another_plugin_id. Por exemplo, poderia ligar a este capítulo do manual do programa com o seguinte tópico:

   <topic label="Help Chapter in Platform Doc"
href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>

Nas versões anteriores à 3.2, as referências a documentos noutros plug-ins foram feitas através da utilização de ".." para ir para o nível do plug-in e, em seguida, através da referência ao ID do plug-in seguido do HREF para o tópico contido no plug-in. A forma recomendada de o fazer actualmente é através da utilização de PLUGINS_ROOT em vez de "..". A utilização desta variável evita estes movimentos para cima e para baixo nas referências e pode ser utilizado para todos os recursos de URLs nos documentos de ajuda (imagens, ligações, ficheiros CSS, ficheiros de script de java, etc.)

Nota:  Ao referenciar conteúdo de outro plug-in, assegure-se de que utiliza o id do plug-in, tal como declarado no ficheiro plugin.xml, e não o nome de directório.  Embora estes sejam um e o mesmo na prática, é importante verificar se se utiliza o ID e não o nome de directório.

Referenciar o Plug-in do Produto.

É frequente colocar-se informações de marca num plug-in que define um produto, como explicámos em Definir um Produto. Os recursos de ajuda no plug-in do produto podem ser referenciados a partir do índice ou de tópicos que utilizem o identificador especial PRODUCT_PLUGIN para o ID do plug-in. Por exemplo,

   href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"

remete para uma folha de estilo (css) que reside no plug-in relativo ao produto actualmente em execução.