A plataforma utiliza seu próprio servidor de documentação para fornecer as páginas reais da Web para a documentação de seu plug-in. Um servidor personalizado permite que a plataforma trate do conteúdo HTML em um navegador de uma forma independente para fornecer suporte reconhecido pelo plug-in. A principal diferença para você como desenvolvedor de plug-in é que tem um pouco mais de flexibilidade na maneira em que estrutura seus arquivos e especifica seus links.
Um plug-in de documentação pode ser executado a partir de um arquivo jar ou descompactado no diretório do plug-in durante a instalação. Um jar de archive de plug-in não é expandido em um diretório de plug-in quando o valor do atributo unpack
do elemento
plugin
está especificado como true no manifesto do recurso. Nesse plug-in, a documentação é compactada no jar do plug-in junto com outros arquivos do plug-in.
Em plug-ins que são executados descompactados, a documentação pode ser entregue em um arquivo zip, evitando problemas que podem ocorrer quando um grande número de arquivos está presente em um diretório de plug-in. No nosso plug-in de exemplo, criamos um subdiretório chamado html. Como alternativa, poderíamos ter colocado nossos arquivos html em um arquivo zip chamado doc.zip. Esse arquivo zip deve retratar a estrutura do arquivo sob o diretório de plug-in. No nosso caso, ele deve conter o subdiretório html e todo o conteúdo de html.
Observe que para plug-ins que executam a partir de um jar, não há necessidade de que a documentação esteja contida adicionalmente no doc.zip e essa configuração do doc.zip em um jar de plug-in não explodido não é suportada pelo sistema de ajuda.
Ao resolver os nomes de arquivos em um plug-in que é executado descompactado, o servidor de ajuda examina rapidamente o arquivo doc.zip para obter documentos antes que ele próprio examine rapidamente o diretório de plug-in. Quando utilizado como link, o argumento em um href é suposto relacionar-se ao plug-in atual. Considere o seguinte link:
<topic label="Ref1" href="html/ref/ref1.html"/>
O plug-in de ajuda procurará este arquivo da seguinte forma:
É possível utilizar um link completo para referir-se a qualquer conteúdo na Web.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
O sistema de ajuda da plataforma utiliza o mesmo esquema de pesquisa do diretório de idioma nacional utilizado pelo restante da plataforma para procurar arquivos traduzidos. (Consulte Arquivos específicos do locale para obter uma explicação dessa estrutura de diretórios). Se estiver utilizando um arquivo doc.zip, deverá produzir um arquivo doc.zip para cada locale e colocá-lo dentro do diretório de locale correto. (Você não deve replicar a estrutura do diretório do código do idioma nl dentro do arquivo doc.zip.)
Além dos diretórios específicos ao código do idioma, o sistema de ajuda verifica o sistema de janelas e os diretórios do sistema operacional ao localizar os recursos de ajuda. A consulta é executada na seguinte ordem: subdiretórios ws, os, nl, em seguida, a raiz do plug-in, até que o recurso seja localizado. Os documentos e outros recursos, como imagens que diferem entre sistemas, devem ser colocados nos diretórios ws ou os para a plataforma específica.
O argumento href também pode referir-se ao conteúdo de outro plug-in. Isso é feito utilizando-se uma notação especial de referência cruzada do plug-in que é resolvida pelo servidor de ajuda:
<topic label="Ref1" href="../"another_plugin_id"/ref/ref1.html"/>
Por exemplo, você pode estabelecer um link a este capítulo do guia do programador utilizando o seguinte tópico:
<topic label="Capítulo de Ajuda no Documento da Plataforma" href="../org.eclipse.platform.doc.isv/guide/help.html"/>
Nota: Ao fazer referência ao conteúdo de outro plug-in, certifique-se de utilizar o ID do plug-in, conforme indicado em seu arquivo plugin.xml e não seu nome de diretório. Na prática, isso é quase a mesma coisa, mas é importante verificar se você está utilizando o ID e não o nome do diretório.
As informações sobre o branding são sempre colocadas em um plug-in que define um produto conforme explicado em Definindo um Produto. Os recursos da ajuda no plug-in do produto podem ser referidos a partir do índice ou dos tópicos que utilizam o identificador especial "PRODUCT_PLUGIN" para o ID do plug-in. Por exemplo,
href="../PRODUCT_PLUGIN/book.css"
faz referência a uma folha de estilo que reside no plug-in do produto em execução atualmente.