GroovyHelp之怀旧归档篇

GroovyHelp简介

  GroovyHelp是一款针对Javadoc及Groovydoc研发的多功能API文档管理软件，它能够帮助Java开发人员、Groovy开发人员以及Android开发人员方便快速地搜索、查阅、比较API文档并对其进行高效管理，从此无需苦苦寻觅chm格式的帮助文档了。可访问GroovyHelp项目首页，获悉GroovyHelp最新信息。

  GroovyHelp的雏形最早设计并开发于2007年年初，记得那时的我还在eBay实习，工作比较舒心，就利用闲暇时间开发了GroovyHelp的第一个版本，该版本相对比较初级，因为它只能将API信息抽取出来，而无法分门别类（比如类、接口、方法、构造方法等）。在2007年到2010年，期间断断续续开发了几个版本，也增加了不少功能，并增强了原有功能（比如支持对API信息进行分类），可惜这些版本的性能和易用性方面都不太好。终于在2011年年初决定将其完全重写，GroovyHelp3就此诞生了，它包含了这些年开发GroovyHelp时汲取的经验和教训，犹如神鸟凤凰般浴火重生。无论是在性能、易用性、健壮性方面，还是功能多样性方面都有了长足的进步。更新此文时，GroovyHelp的最新版本是groovyhelp-5.0.0-rc_b2015012501。

GroovyHelp主要特性

1. 根据输入关键字，查找类，接口，方法等帮助信息（支持模糊查询）
2. 支持全文检索，并高亮搜索结果（支持模糊检索）
3. 以树型结构完整展现文档的整体结构及文件结构
4. 支持源码关联，即查看文档所对应的源码，并语法高亮显示源码
5. 提供帮助文档比较功能（比如Java 7与Java 6帮助文档间的比较），高效掌握API变化
6. 自带Java各包的API使用及Groovy编程示例，方便参考和查阅
7. 支持JDK1.4+自带的Javadoc生成的帮助文档
8. 支持Groovy1.8+自带的Groovydoc生成的帮助文档
9. 支持英文及中文API文档
10. 语法高亮网页中的代码片段
11. 无需解压文档及源码ZIP压缩包，节省磁盘空间
12. 支持在线的Javadoc（比如jexcelapi的在线Javadoc）
13. 用户可以自由选择所需的jre1.6.0+（可通过环境变量GROOVYHELP_JAVA_HOME指定）
14. 提供多种浏览器(JFX浏览器、本地浏览器、简易浏览器)
15. 为中国大陆用户提供在线字典功能
16. 同时支持Windows、Linux以及Mac OS X

GroovyHelp安装和使用

1. 从GroovyHelp项目主页上下载最新稳定版本到本地（压缩包的命名规则是：groovyhelp-版本号-(ea|rc|ga)_构建日期编号.zip）

2. 解压groovyhelp-X.X.X-XX_yyyyMMddXX.zip，注意：解压路径中不要有中文和空格。
   
   

3. 设置GROOVYHELP_JAVA_HOME环境变量，将其值赋为Oracle JDK/JRE 1.6.0u10+所在路径（比如：D:\_DEV\Java\jdk1.6.0）。如果在机器上没有相关JDK/JRE，可以到Oracle官方下载页面下载相应的JDK/JRE。注：如果不设置GROOVYHELP_JAVA_HOME环境变量，那么将使用系统默认的JRE，可能不是GroovyHelp所需要，会导致GroovyHelp无法正常使用。
   
   

4. 双击执行groovyhelp.exe（用于Windows）或groovyhelp（用于Linux和Mac OS，执行之前需通过“chmod 555 groovyhelp”修改其访问权限），启动后界面如下所示：
   
   

5. 添加API文档（本地的或在线的均可）

   • 5.1 点击菜单Docs -> Manage Docs，显示如下界面：
     
     
   • 5.2 点击上述界面中的“Add”，显示如下界面：
     
     
   • 5.3 在上述界面中输入“Doc Name”（文档名称）、“Doc Home”（API文档所在路径(压缩包或文件夹均可)，或在线文档的index.html页面的url，比如http://jexcelapi.sourceforge.net/resources/javadocs/2_6_10/docs/index.html。如果http://jexcelapi.sourceforge.net/resources/javadocs/2_6_10/docs/可跳转至index.html页面，则输入http://jexcelapi.sourceforge.net/resources/javadocs/2_6_10/docs/亦可）、而“Src Home”（源码路径(压缩包或文件夹均可)）是可选的。最后点击“Finish”按钮对AIP文档创建索引（如果是在线文档则还会有下载文档这一过程）。注：如果对在线文件创建索引，则会遇到某些大页面（1M~2M）下载速度比较慢现象，请耐心等待，等待时间长短决定于页面文件大小及带宽。而创建索引时CPU使用率保持在95%~100%属正常现象，该过程比较耗资源。
     • a，为本地文档创建索引：
       
       
     • b，为在线文档创建索引（下图所示的是下载过程）：
       
       
   • 5.4 索引创建完毕之后，显示如下界面（顺便提一下，通过点击以下界面中的“Enabled”一列中的复选框可“启用”或“停用”API文档，这是出于性能方面的考虑，建议不要同时启用超过5份API文档）。
     
     

6. 点击上述界面中“Close”按钮，关闭该对话框显示以下界面，开始使用API文档：
   
   

   • 6.1 “单击”文档树中的API信息节点查看相关内容：
     
     

   • 6.2 如果设置了“Src Home”，则还可以通过点击浏览器中的“J”图标按钮查看相关源码：
     
     

   • 6.3 如果对API信息之外的内容感兴趣，可以点击“Resource” TAB页，查看其他资源信息：
     
     

   • 6.4 如果需要根据关键字搜索API信息，则可以点击“Index” TAB页，输入API关键字（比如write），支持模糊搜索（?表示单个字符，*表示多个字符），双击某个搜索结果项，显示相关信息。如果与双击的搜索结果与多个API信息匹配，那么将显示分类页面。点击分类页面中的其中一项即可查看相关内容。（注：可以通过选中或取消“Scope”中的分类复选框以限定搜索范围）
     
     

   • 6.5 点击上述分类页面中的某个链接，查看相关API信息：
     
     

   • 6.6 如果需要进行更宽泛的搜索（不仅限于API信息），则可以点击“Search” TAB页面，输入关键字，回车或点击搜索按钮进行搜索，支持模糊搜索（?表示单个字符，*表示多个字符），双击搜索结果项查看相关信息（页面中高亮部分便是关键字指定内容）：
     
     

   • 6.7 有时对某些Java API的用法不太熟悉，可以点击“Examples” TAB页，双击某个包，点击相关链接查看相应用法实例：
     
     

   • 6.8 如果需要比较两个版本API文档的差异，可以通过点击“Tools” -> “Compare Docs”，显示如下对话框。选择比较的两个文档以及比较范围，点击“Compare”按钮进行比较，点击各个API信息节点(+)查看变化内容：

     • a，设置API文档比较对象及范围
       
       
     • b，点击各个节点查看变化内容
       
       

   • 6.9 如果觉得页面字体比较小，可以通过主界面右下角的调节器进行调整（双击可复位默认值100%），该功能自3.2.7 GA版本开始移至“Tools”：
     
     

GroovyHelp版本升级

1. 访问GroovyHelp项目首页下载最新版本的GroovyHelp。
2. 删除老版本GroovyHelp所在目录下除“idx文件夹”以及“用户自己的文件或文件夹（比如一些放置在GroovyHelp所在目录下的docs文件）”外的所有文件和文件夹。
3. 将新版本GroovyHelp压缩包解压到老版本所在目录。
4. 升级完毕

注：升级后第一次启动会比较缓慢，请耐心等待。

GroovyHelp使用技巧

1. 使用快捷键关闭或切换TAB页。ctrl+w关闭当前TAB页，ctrl+q关闭所有TAB页，ctrl+e关闭除当前TAB页外的其他TAB页，ctrl+Tab切换TAB页。
2. 如果GroovyHelp需要在多处使用，比如想通过移动硬盘在多台电脑里使用GroovyHelp，但又不想一遍又一遍为API文档创建索引，那么可以在GroovyHelp的解压目录下新建docs目录，并将文档放置其中。以后即使GroovyHelp整个解压文件夹被移动，也不会影响对API文档的使用。
3. 如果发现索引文件越来越大，可以通过点击选中“Tools” -> “Optimize Index Before Exit”菜单项，在退出应用前，对索引文件进行压缩优化，使其大小大幅减小。注：该优化操作可能需要几分钟才能完成，所以不建议频繁优化。
4. 在Windows系统下，定期做一下磁盘整理。

GroovyHelp常见问题

1. 对于在Windows 7(x64)下使用64位JVM无法正常运行GroovyHelp的朋友，建议使用32位JVM，这是由于GroovyHelp所依赖的个别组件对64位JVM支持得不太好 
2. 在Mac OS X下，时常出现打开页面或关闭页面时JVM崩溃的情况，这是因为GroovyHelp所依赖的个别组件对Mac OS X支持得很不好，所以建议通过设置GROOVYHELP_JAVAFX_HOME环境变量以启用JFX浏览器，而自JDK1.7.0u04开始，Oracle官方JDK开始支持Mac OS X，并自带了JavaFX SDK，则无需设置该环境变量。在Mac OS X 下，推荐使用Oracle官方JDK1.7.0u4+ （比如JDK1.7.0u05）

结束语

  相信目前GroovyHelp的这些功能足以应对API信息的各类查阅需求，如果发现什么BUG或有些什么好的建议可以通过GroovyHelp的Issues页面或博客留言反馈。如果您使用的是GroovyHelp 3.2.0 GA以前版本，可以参考《JAVA程序员帮助文档查看利器：GroovyHelp》。