由于插件会向平台添加功能,所以通常要添加描述新功能的文档。如何构建该文档以让用户看到一套整合的文档,而不是许多单独添加项?目录定义提供了一些机制来自顶向下和自底向上地构建文档。
自顶向下嵌套是一种技术,用来定义主控目录,它引用所有其它包含的目录。自顶向下嵌套是将已知内容分割为较小块的简便方法。使用自顶向下嵌套,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>