构建嵌套文档结构

由于插件会向平台添加功能,所以通常要添加描述新功能的文档。如何构建该文档以让用户看到一套整合的文档,而不是许多单独添加项?目录定义提供了一些机制来自顶向下和自底向上地构建文档。

自顶向下嵌套

自顶向下嵌套是一种技术,用来定义主控目录,它引用所有其它包含的目录。自顶向下嵌套是将已知内容分割为较小块的简便方法。使用自顶向下嵌套,link 属性用在目录定义中以引用链接的目录,而非提供一个 href。 

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

基本结构保持相同(概念、任务、引用),但单独的目录可以自由发展。它们可能按顺序链接至其它子目录。

自底向上组合

自底向上组合更加灵活,因为它允许新的插件决定文档应在目录结构的哪个位置存在。自底向上组合使用 anchor 属性来实现。目录定义命名锚点,其中的其它插件可以添加文档。在我们的示例中,我们可以添加锚点以使插件可以在概念、任务和引用节之间添加附加资料。

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

其它插件就可以从其插件向锚点添加。这是在定义目录时使用 link_to 属性完成的。

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Late breaking info about concepts">
	<topic>
		...
	</topic>
</toc>