Nota: o sistema de ajuda ainda está em desenvolvimento e esperam-se algumas alterações antes de alcançar estabilidade. Nesse estágio é possível solicitar feedback de pessoas que adotaram o sistema anteriormente, entendendo-se que os detalhes dos mecanismos de contribuição poderão ser alterados nos pontos de ruptura. |
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 topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)* ) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
Marcação de Configuração para Infosets (isto é o que vai dentro do arquivo de manifest) :
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset label CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
Marcação de Configuração para Inserir Ações (isto é o que vai dentro do arquivo manifest de ações) :
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
Geralmente, um plug-in que precisa fornecer ajuda online irá definir seus próprios manifests de tópicos e as ações de manifest necessárias para ligar os tópicos ao lugar correto.Ao final, o sistema de ajuda é configurado para ser lançado como algumas ações, e o ID do conjunto de informações pode ser utilizado para agir desse modo.
Há quatro tipos de elementos XML que um plug-in pode utilizar: o tópico, o infoset, as ações e os elementos de inserção.
O elemento de tópico
Com relação aos elementos de tópicos, todos os tópicos são contribuintes como partes do elemento de contêiner de tópicos.Eles podem ter uma estrutura hierárquica, ou podem ser listados como uma lista simples. O manifest de tópicos é exibido como uma origem de dados para tópicos intercalados futuros e para a futura organização dentro de uma rede integrada, com diferentes perspectivas de exibição Além disso, os tópicos podem atuar mediante seus IDs específicos, mas um tópico somente pode atuar dentro de um grupo de tópicos ao especificar o ID dos tópicos presentes ou do elemento de tópico. Mais tarde, ao ligarem-se os tópicos às exibições ou a outros tópicos, a estrutura definida no manifest de tópicos é mantida (sujeita às alterações feitas pelas ações de inserção).
O elemento de tópico é o "burro de carga" da estrutura de navegação. Há três utilizações típicas para o elemento tópico:
1. Fornecer um link para o arquivo de documentação - geralmente um arquivo HTML.
2. Agir como um contêiner para outros tópicos, em um mesmo manifest ou em outro.
3. Fornecer um ponto de inserção para outros tópicos, no 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="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 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="Starting the IDE" href="concepts/blah.htm"
/>
...
</tópicos>
3. Tópicos são pontos de inserção
Os tópicos podem ser utilizados como pontos de inserção. Eles fornecem um local lógico para outros tópicos tentarem e se mesclarem ao redor. Para atuar como um ponto de inserção, o tópico precisa ter um atributo de identificação.
O elemento infoset
Um conjunto de informações é um ponto de entrada dentro de uma documentação da Web. Pode-se pensar nele como uma coleção de exibições.
As exibições têm a intenção de fornecer agrupamentos semânticos de alto nível dentro da documentação da Web. Elas são definidas utilizando-se o elemento infoview definido dentro de um infoset. O conjunto de documentação pode utilizar uma exibição para produzir a inicialização, as tarefas e as seções de referências (ou outras exibições para produzir definições de grupo).A plataforma não especifica as seções atuais, somente o mecanismo para defini-las.
Por exemplo, pode haver uma "exibição de tarefa" definida que é a mesclagem de todos os tópicos a partir da perspectiva "como fazer alguma coisa". Outra exibição, "uma exibição de componente" também pode ser definida de acordo com a árvore de tópicos que exibe todos os componentes e sua documentação.
O elemento infoview representa um contêiner para tópicos que podem ser "divididos" entre os plug-ins É uma perspectiva da documentação como um todo. Pode haver ocasiões quando um número de diferentes plug-ins contribuem para o mesmo componente de documentação lógica. Esse elemento assegura que durante uma "exibição de componente", eles estejam corretamente mesclados dentro de uma exibição coerente.
O elemento ações
O manifest de ações contém ações de script a serem executadas em tópicos e exibições. Atualmente, há somente um tipo de ação, a ação de inserção, que é utilizada para escrever tópicos e exibições dentro de uma rede de informações integradas, com múltiplas exibições.
As ações são ações estruturais (inseridas) e, assim, aplicam-se a determinada infoview. Desse modo, todas as ações de inserção em um manifest, constroem a hierarquia dos tópicos em um infoview.
O elemento de inserção
Uma das partes mais complicadas de uma navegação por componentes é como criar uma estrutura de informações integradas com um fluxo contínuo de navegação. Para fazer isso, precisamos de um mecanismo para publicar os pontos de inserção, escolher quais pontos de inserção nós queremos utilizar e indicar onde queremos inserir os tópicos (pai, filho, antes, depois).
Os pontos de inserção podem ser tópicos ou exibições. Um tópico indica sua disposição em ser um ponto de inserção ao fornecer uma identificação. É obrigatório que as exibições tenham identificação. Somente identificações completas são utilizados como referências. Por exemplo, o identificador completo do tópico <identificador do tópico ="conceitos" etiqueta="conceitos"> no plug-in org.eclipse.help.examples.ex1 é org.eclipse.help.examples.ex1.concepts.
Desde que os pontos de inserção estejam tipicamente localizados em outros plug-ins, e esses plug-ins não estejam instalados, pode-se especificar um ponto de inserção alternativo.Por padrão, se nenhuma das escolhas for bem sucedida, o tópico permanece sob a hierarquia de seu componente. O atributo "para" especifica o ponto de inserção de destino. O tópico especificado pelo atributo "de" é o tópico que está sendo inserido A seguir alguns caminhos possíveis para inserir um tópico e sua utilização é especificada com um atributo:
São fornecidas opções de inserção alternativas, e seriam executadas quando as primeiras não pudessem ser. Os sub-elementos de inserção aninhados do elemento de inserção fornecem essas alternativas. Isso pode ser considerado como um mecanismo "fall back", em que se uma ação de inserção falhar, a ação de inserção aninhada será executada. Uma vez que o ponto de inserção primeiramente escolhido foi satisfatório, os outros pontos de inserção alternativos são ignorados.
Exemplos:
A seguir um exemplo da utilização do ponto de extensão contribuições. 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 de contribuição a seguir, poderia também ser criada com várias combinações de tópicos e arquivos de ações.)
(no arquivo plugin.xml)
<!-- Utilize o ponto de extensão de contribuição do Sistema de Ajuda, tópicos, -->
<!-- e os arquivos de contribuição de ações. Para esclarecer, o ponto de extensão é utilizado -->
<!-- duas vezes, uma vez para definir o Infoset e sua exibição e a outra para definir os -->
<!-- Tópicos e suas ações associadas.
-->
<extension points="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<tópicos name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- Configurar a contribuição de ajuda para esse plug-in
-->
<!-- Essa parte deve estar em um plug-in de documentação
-->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(no arquivo infoset.xml)
<!-- Definir o Infoset e suas exibições. -->
<infoset id="ex1InfosetId" label="%help_system_example">
<infoview id="topicsView" label="%topics"/>
</infoset>
(no arquivo infosetTopics.xml)
<!-- Agora defina um tópico de "contêiner" que contenha todos os seus tópicos gerais. Isso facilita -->
<!-- a rápida inserção de todos esses tópicos gerais sob a exibição no -->
<!-- Infoset. -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topics id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
Definir tópicos contidos nos tópicos gerais acima:
(no arquivo topics.xml)
<topics id="topics">
<topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
<topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
</tópico>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</tópicos>
Agora definir as ações de inserção necessárias para criar a hierarquia da documentação:
(no arquivo infosetActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(no arquivo topicsActions.xml)
<inserir de="org.eclipse.help.examples.ex1.topLevelTopics"
para="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">Aqui está o resultado da hierarquia da documentação no Workbench do Eclipse:
<inserir de="org.eclipse.help.examples.ex1.aConceptId"
para="org.eclipse.help.examples.ex1.concepts" as="child"/><inserir de="org.eclipse.help.examples.ex1.aTaskId"
para="org.eclipse.help.examples.ex1.tasks" as="child"/><inserir de="org.eclipse.help.examples.ex1.aReferenceId"
para="org.eclipse.help.examples.ex1.references" as="child"/><inserir de="org.eclipse.help.examples.ex1.aSampleId"
para="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
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 opcional do sistema de ajuda da UI fornecida com a plataforma Eclipse suporta completamente o ponto de extensão contribuições.