Construindo estruturas de documentação aninhadas

Como os plug-ins contribuem com funções para a plataforma, é comum adicionar documentação que descreva a nova função.  Como essa documentação pode ser estruturada para que o usuário veja um conjunto coeso e completo de documentos, em vez de várias contribuições individuais?  A definição do índice fornece mecanismos para a construção de documentação em dois modos: de cima para baixo e de baixo para cima.

Aninhamento de Cima para Baixo

Aninhamento de cima para baixo refere-se à técnica de definição de um índice principal que se refere aos outros tocs incluídos.  É um método adequado para dividir conteúdo conhecido em partes menores.  Com ele, o atributo link é utilizado na definição do índice para referir-se a tocs com links efetuados, em vez de fornecer um href

<toc label="Exemplo de Ajuda On-line" topic="html/book.html">
	<topic label="Conceitos">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tarefas">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Referência">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

A estrutura básica permanece a mesma, (Conceitos, Tarefas, Referência), mas os tocs individuais têm liberdade para desenvolver-se.  Podem, por sua vez, efetuarem link com outros sub-índices.

Composição de Baixo para Cima

A composição de baixo para cima é mais flexível, pois permite que novos plug-ins decidam onde a documentação deve existir na estrutura do toc.  Ela é realizada com atributos anchor.  Um toc define pontos de âncora designados em que outros plug-ins podem contribuir com documentação.  Em nosso exemplo, poderíamos incluir âncoras para que os plug-ins pudessem contribuir com material adicional entre as seções de conceitos, tarefas e referência.

<toc label="Exemplo de Ajuda On-line" topic="html/book.html">
	<topic label="Conceitos">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tarefas">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Referência">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

Outros plug-ins podem contribuir com a âncora a partir de seu plug-in.  Isso é feito utilizando o atributo link_to ao definir um toc.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Últimas informações sobre conceitos">
	<topic>
		...
	</topic>
</toc>

Copyright IBM Corporation e outros 2000, 2003.