Construir estruturas de documentação imbricadas

À medida que os plug-ins contribuem com funções para a plataforma, é natural adicionar documentação que descreva a nova função.  Como deve esta documentação ser estruturada para que o utilizador veja um conjunto de documentação coerente e completo em vez de muitos contributos individuais?  A definição do índice faculta mecanismos para construir a documentação tanto de cima para baixo como de baixo para cima.

Imbricação de cima para baixo

A imbricação de cima para baixo refere-se a uma técnica de definir um índice principal que remeta para todos os outros índices incluídos.  A imbricação de cima para baixo é um método conveniente para dividir conteúdo conhecido em pedaços mais pequenos.  Com a imbricação de cima para baixo, o atributo link é utilizado na definição do índice para remeter pata os índices ligados, ao invés de fornecer um tag href

<toc label="Exemplo de Ajuda Online" topic="html/manual.html">
	<topic label="Conceitos">
		<link toc="toc_Conceitos.xml" />
	</topic>
	<topic label="Tarefas">
		<link toc="toc_Tarefas.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 índices individuais ficam livres para evoluir.  Por seu turno podem ligar a outros sub-índices.

Composição de baixo para cima

A composição de baixo para cima é mais flexível no sentido em que deixa os novos plug-ins decidirem onde deve existir documentação na estrutura do índice.  A composição de baixo para cima realiza-se com atributos anchor.  Um índice define pontos de âncora denominados onde os outros plug-ins podem contribuir com documentação.  No nosso exemplo, podíamos adicionar âncoras para que os plug-ins contribuíssem com material adicional entre as secções conceitos, tarefas e referência.

<toc label="Exemplo de Ajuda Online" topic="html/manual.html">
	<topic label="Conceitos">
		<link toc="toc_Conceitos.xml" />
		<anchor id="pós-Conceitos" />
	</topic>
	<topic label="Tarefas">
		<link toc="toc_Tarefas.xml" />
		<anchor id="pós-Tarefas" />
	</topic>
	<topic label="Referência">
		<link toc="toc_Ref.xml" />
		<anchor id="pós-Referência" />
	</topic>
</toc>

Os outros plug-ins podem contribuir para a âncora a partir do respectivo plug-in.  Tal processa-se com o atributo link_to na definição de um índice.

<toc link_to="../com.example.helpexample/toc.xml#pós-Conceitos" label="Informações de última hora sobre conceitos">
	<topic>
		...
	</topic>
</toc>