制作eclipse样式的帮助系统

 eclipse自带的联机帮助非常强大,由Help/Help Contents打开.能全文检索,定义书签等等

最近做的项目发布的时候要做个比较友好的帮助系统,就想到了用eclipse完成,下面简单介绍一点经验

一.原理

    eclipse的联机帮助其实是一个小型的B/S系统,我们点Help/Help Contents的时候,eclipse就在后台启动一个Tomcat+Lucence,而我们看到的是由eclipse自带的浏览器展示出来的网页.因此我们可以先把帮助制作成Html或者是Jsp等格式.

    然后我们需要把这些网页形式的帮助文档制作成eclipse能够接受的"书".Eclipse帮助系统左边显示的一本本书其实都是Eclipse的插件,扩展点是TOC(table of contents),eclipse启动的时候会在eclipse.exe的目录下和links文件夹下的所有link指向的目录下 加载插件,如果有扩展点为TOC的插件,就把它作为联机帮助系统中的一本书.因此我们就需要用eclipse的插件开发环境,把html的帮助文档包装成插件.其实这步比较简单,(网上的例子成把抓),eclipse插件开发的向导中就有Plug-in with sample help content的模板.用到的扩展点就是org.eclipse.help.toc

    最后在发布系统的时候,需要一个eclipse环境,因为插件要运行在eclipse平台上.官方的帮助文档建议的minimal stand-alone help system就是RCP runtime binary 加上以下插件

org.apache.lucene
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.ui.forms
二.具体步骤

1、制作帮助

在eclipse里新建一个插件工程，然后选择添加TOC扩展，在扩展的右边可以选择一个主TOC，默认是testToc.xml,默认为

这里用link相当于把toc.xml的内容贴过来，而这个级别的字节点在帮助系统中显示出来的就是跟JDT和PDT等同一个级别的帮助。自己可以多写几个toc.xml然后link过来，便于分类和扩展

在每个toc.xml中，用href指定文档的路径，如这里的Main Topic对应的文档就是一.html，它有一个子类，层次结构很清楚，就不废话了

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents">
    <topic label="Main Topic"  href="html/一.html"> 
        <topic label="Sub Topic" href="html/subtopic.html"/> 
    </topic>
    <topic label="Main Topic 2"/>
</toc>

 

制作好了以后，可以以eclipse应用程序运行来查看结果，在运行后的eclipse中选择help content菜单，就可以看到Main Topic了。

最后把工程打包出来，得到的jar文件，就是做好的帮助插件

2、配置帮助系统运行环境

开始分析了，这个插件运行其实就是启动一个eclipse，也就是说做好的插件需要一个eclipse，官方的文档说可以只要一个rcp binary加上开头说的那些插件即可

然后把第一步做好的插件丢到配好的rcp binary的plugin目录下，当然为了扩展性，可以用link的方式，不管怎么样，这步相当于安装一个eclipse的插件一样

注意点：在这个配好的小型eclipse下，要注意配置help插件的属性，打开org.eclipse.help(后面是版本号)，修改里面的ignoredTOCS=的属性，让系统本身的帮助文档不显示出来

注意点2：文档不能是中午名

看来是URLencoding的问题，但是我一般的tomcat都可以设好URLencoding的，但这里的tomcat是eclipse带的，找不到可以配置的地方，以后再解决吧

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Test TOC" topic="html/toc.html">
    <link toc="toc.xml" />
</toc>