Construir estructuras de documentación anidadas

Como los conectores contribuyen suministrando funciones a la plataforma, es habitual añadir documentación que describa las nuevas funciones. ¿Cómo se puede estructurar esta documentación para que el usuario la vea como conjunto completo y coherente, en vez de como muchas contribuciones individuales? La definición de tabla de contenido proporciona mecanismos para construir la documentación siguiendo dos enfoques, el ascendente y el descendente.

Anidación descendente

Llamamos anidación descendente a la técnica que permite definir una tabla de contenido maestra que haga referencia a las demás tablas de contenido incluidas. La anidación descendente es un método cómodo de desglosar el contenido conocido en elementos más pequeños. En la definición de la tabla de contenido se utiliza el atributo link para hacer referencia a las toc enlazadas, en lugar de proporcionar un atributo href

<toc label="Ejemplo de ayuda en línea">
	<topic label="Conceptos">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tareas">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Consulta">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

La estructura básica no varía (Conceptos, Tareas, Consulta), pero las toc individuales son libres de ir desarrollándose y, a su vez, pueden estar enlazadas con otras subtablas de contenido.

Composición ascendente

La composición ascendente es más flexible en el sentido de que permite a los nuevos conectores decidir si la documentación debe existir en la estructura de la toc. Esta composición se logra mediante atributos anchor. Una toc define puntos de ancla con nombre en los que los otros conectores pueden contribuir suministrando documentación. En nuestro ejemplo, podríamos añadir anclas para que los conectores tuvieran la posibilidad de contribuir con nuevas materias en las secciones de conceptos, tareas y consulta.

<toc label="Ejemplo de ayuda en línea">
	<topic label="Conceptos">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tareas">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Consulta">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

Luego, los otros conectores pueden contribuir en el ancla de su propio conector. Para ello se emplea el atributo link_to en el momento de definir una tabla de contenido.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Información de última hora sobre conceptos">
	<topic>
		...
	</topic>
</toc>

Copyright IBM Corp. y otros 2000, 2002.