20.8 加入帮助（toc）

如图20.10所示，本节实例将演示如何在plugin.xml添加帮助扩展点；如何创建帮助左部的结点树；如何在帮助内容中创建超链接，链接到另一个帮助文件。

图20.10 帮助

20.8.1 修改plugin.xml文件，设置3个帮助的扩展点

打开plugin.xml文件的编辑框，将如下代码块插入到最后一行的</plugin>项之前：

<toc

file="toc.xml"

primary="true">

</toc>

<toc

file="other_toc.xml"

primary="true">

</toc>

</extension>

说明：

● org.eclipse.help.toc是帮助的扩展点。

● toc是帮助目录项的设定。

● toc的file是指定帮助目录文件（还没编写，接下来会完成这两个xml文件）。

● toc的primary为该项帮助目录是否显示在帮助窗口中，true为显示。

● 如图20.10所示左边的结点树，toc.xml对应于“myplugin帮助”结点，other_toc.xml对应于“myplugin的新版功能”结点。

20.8.2 编写帮助目录文件toc

这两个文件应放置在项目的根目录下，和src目录平级，如图20.11所示。

图20.11 目录结构图

帮助目录文件是一个XML文件，其内设定了界面结点和HTML帮助页面之间的映射关系。先给出第一个文件toc.xml的代码，如下：

<?xml version="1.0" encoding="UTF-8"?>

</topic>

</topic>

</toc>

说明：

● topic：设置帮助目录中的结点。

● topic的lable：结点显示的名称。

● topic的href：结点对应的帮助文件的路径及文件名，也可以是网址（还没编写对应的帮助文档，下一步会完成它们）。

下面再给出另一个帮助目录文件other_toc.xml，代码如下：

<?xml version="1.0" encoding="UTF-8"?>

</toc>

20.8.3 创建相应的帮助文档

帮助文件创建在插件项目的根目录下，和src目录平级，目录结构如图20.11所示。帮助文件都是一些标准的.html格式的网页文件，这里仅给出<topic label="透视图" href= "contexts/1.html">项对应的1.html文件，其他的.html文件可以从配书光盘中获得。1.html的内容如下：

<HTML>

<BODY>

透视图 <A HREF="other/by_1_link.html">一个链接</A>

</BODY>

</HTML>

在1.html页面中包含了一个超链接“other/by_1_link.html”，这个文件并不需要在帮助目录文件toc.xml中注册。

20.8.4 运行插件

在新Eclipse环境中选择主菜单“帮助→帮助内容”命令，以查看本节实例效果。如果采用精简方式来启动插件，那么这里会出错，弹出一个错误提示框（图20.12）告知去查看日志以确认错误原因。于是打开“C:\runtime-Eclipse应用程序\.metadata\.log”文件，在文件未尾看到异常为“CoreException: 启动应用程序服务器时发生了异常”，从错误弹出框和.log日志异常可以大致判断Eclipse帮助是运行在一个WEB容器之中的。查看“运行”窗口的插件列表，果然发现了tomcat插件，如图20.13所示。

选中tomcat和它的语言包插件nl1对应的复选框。再次启动新的Eclipse环境，还是无法打开帮助，于是再次查看.log文件，发现异常“CoreException: 不能获取插件 org.eclipse.help.webapp的位置”。回到运行窗口选中help.webapp插件和它对应的语言包插件nl1对应的复选框，再次启动新的Eclipse环境后，打开帮助正常，没有再出现错误。