Definindo os Tópicos de Ajuda

Agora que temos nossos arquivos de conteúdo de amostra, é possível criar um arquivo de tópicos. Um arquivo de tópicos define os pontos de entrada chave nos arquivo de conteúdo HTML mapeando um id de tópico e uma etiqueta para uma referência em um dos arquivos HTML. Um arquivo de tópicos age como um índice de um conjunto de conteúdo HTML.

Os aplicativos que estão sendo migrados para a plataforma podem reutilizar a documentação existente utilizando o arquivo de tópicos para definir pontos de entrada naquela documentação.

Um plug-in pode ter um ou mais arquivos de tópicos. Os arquivos de tópicos são, algumas vezes, referidos como arquivos de navegação visto que eles descreverem como navegar no conteúdo HTML. Nosso exemplo de documentação é organizado em três categorias principais: conceitos, tarefas e referências. Como fazemos arquivos de tópicos que representem esta estrutura?

Poderíamos fazer um arquivo de tópicos grande, ou poderíamos criar um arquivo de tópicos separados para cada categoria principal de conteúdo. Essa decisão pode ser tomada de acordo com o modo de trabalho em conjunto de suas equipes de documentação. Se um autor diferente possuir cada categoria, será melhor manter arquivos de tópicos separados para cada categoria.  Ele não é regido pela arquitetura da plataforma.

Nesse exemplo, criaremos um arquivo de tópicos para cada categoria de conteúdo principal. Para um número tão pequeno de arquivos, pode não ser necessário ter arquivos de tópicos separados para cada categoria.  Conectaremos esse exemplo como se tivéssemos muitos arquivos a mais ou como se tivéssemos separado autores que possuíssem cada categoria de conteúdo.

Nossos arquivos se parecem com este:

topics_Concepts.xml

<topics id="conceptsAll">

 <topic label="Concept1" href="doc/concepts/concept1.html">

     <topic label="Concept1_1" href="doc/concepts/concept1_1.html"/>

     <topic label="Concept1_2" href="doc/concepts/concept1_2.html"/>

 </topic> 
</topics>

topics_Tasks.xml

<topics id="tasksAll">

 <topic id="plainTasks" label="Plain Stuff">

 <topic label="Task1" href="doc/tasks/task1.html"/>

 <topic label="Task2" href="doc/tasks/task2.html"/>

 </topic> <topic id="funTasks" label="Fun Stuff" >

     <topic label="Task3_1" href="doc/tasks/task3_1.html"/>

     <topic label="Task3_2" href="doc/tasks/task3_2.html"/>

 </topic>

</topics>

topics_Ref.xml

<topics id="refAll">

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

 <topic label="Ref2" href="doc/ref/ref2.html"/>

</topics>

Os tópicos são contribuídos como parte do elemento do contêiner dos tópicos. Um tópico pode ser um simples link ao conteúdo.  Por exemplo: "Task1" fornece uma etiqueta e um href vinculando ao conteúdo.  Um tópico pode também ser um agrupamento hierárquico de subtópicos sem conteúdo próprio.  Por exemplo: "Fun Stuff" possui somente uma etiqueta e subtópicos, mas nenhum href .  Os tópicos também podem fazer ambas ascoisas.  "Concept1" possui um href e subtópicos.

Quando utilizado como um link, o argumento em um href é visto como parente do plug-in atual. 

Quando iniciamos a conexão desses tópicos na Web com documentação integral, nos referimos a eles pelos seus ids. Somente os tópicos com um id podem ser manipulados. Para conectar todos os subtópicos de um determinado tópico, podemos fazer a conexão no tópico pai.  Por exemplo: conectar em "Concept1" também conectaria em "Concept1_1" e em "Concept1_2."   

Depois, modificaremos o plugin.xml para incluir as contribuições reais apontando para esses arquivos.