第十一天：我需要一个帮助Plug-in

作者：梁祺 （[e-mail])

 

来自：http://www.benisoft.net/day11/index.html

 

今天我们来为Itinerary创建帮助plug-in。一般我们都会将帮助内容放在一个单独的plug-in里，但Eclipse 也允许帮助内容和程序在同一个plug-in里。不过前者更加常见也更加规范。

同样，我们需要创建一个新的plug-in项目，选择"File -> New -> Others"， 在向导对话框里选择Plug-in Project，项目名称为"eclipse.tutorial.itinerary.help", 略微有些不同的是，帮助plug-in没有任何代码，所以可以把勾选项Create a Java project去掉。 点击Next按钮，将plug-in的名称改为"Itinerary Help"，再点击Next按钮。 选择模板"Plug-in with sample help content"，点击Next按钮。

选择Primary，这样会生成标准的Eclipse帮助结构。点击Finish按钮生成项目。标准的Eclipse帮助结构有五个大类。

这五个大类分别是：

• Getting Started：提供简单教程，帮助用户上手。
• Concepts：应用所涉及的一些概念或术语的解释。
• Tasks：告诉用户如何完成一些任务，也就是How-to。
• Reference：比较详细的帮助内容，一般会按界面来安排，比如视图，详细说明视图中的所有菜单，按钮，以及 每个控件等等。
• Samples：存放一些例子，比如报表软件可以提供一些报表的例子。

将包含该帮助plug-in的Eclipse启动起来后，我们选择"Help -> Help Contents"， 在帮助左侧就能看到这五大类的帮助内容。

我们回过来看一下项目。在Package Explorer View里，可以看到html目录里包含很多HTML文件，这些是帮助的内容。 下面还有很多toc开头的XML文件，这些文件定义了帮助的结构，也就是确定HTML文件在帮助中的位置，以及相互关系。

双击plugin.xml在Plug-in Editor中打开，来到Extensions子页，可以看到该帮助plug-in扩展了org.eclipse.help.toc 这个扩展点，并定义了若干个TOC（Table of Contents），TOC定义了帮助的结构，它本身不包含任何帮助内容。 每个TOC都关联一个XML文件。其中第一个TOC，它的Primary属性为true，这意味着这个TOC是根TOC， 将作为一个根节点出现在Eclipse的帮助系统中，其他的TOC都挂接在这个根TOC下。如果帮助plug-in需要不止一个根节点， 可以设置多个TOC的Primary属性为true，这时需要仔细关联其他TOC到正确的根TOC下。

我们打开第一个TOC的XML文件，也就是toc.xml文件。Eclipse为TOC XML文件提供了编辑器方便查看和编辑， 我们可以看到该TOC定义了两个主题，Main Topic 和Main Topic 2，第一个主题的内容存放在html/maintopic.html，并且它还有一个子主题， 它内容存放在html/subtopic.html里。但是由于这个TOC是根TOC，这些主题是不会被显示出来的， 当用户在帮助中选择这个根节点是，显示的是html/toc.html。我相信这是模板的一个Bug。

我们再来看看tocconcepts.xml，这里需要注意一下Anchor属性，Concepts TOC被链接到toc.xml#concepts上， 这意味着在根TOC上会自动创建一个锚点，用于放置Concepts的内容。这样不同的TOC就被链接在一起，形成一个树状结构， 避免维护一个大而全的TOC。Concepts下面定义了两个主题，也是Main Topic和Main Topic 2。

Concepts的第一个主题Main Topic的内容存放在html/concepts/maintopic.html。

通过这个例子，我们可以了解Eclipse的帮助是怎么组织的，帮助的文字图片都是以HTML文件的形式编写的， 而帮助的结构是由TOC XML文件确定的，也就是指定主题所对应的HTML文件，以及主题之间的父子关系。 这种内容和结构分开的做法使得Eclipse帮助的维护非常的简单和清晰。