Javadoc转换chm帮助文档的四种方法总结

关键词

Javadoc chm 转换 jd2chm javadoc2chm javadoc2help Javadoc2chm 中文乱码 李顺利

 

 

前言

         朋友，当您在一个项目完成后，是不是需要把你的源码打包并且把注释打成 Javadoc 交给客户， Eclipse 或者 MyEclipse 自动打成的 Javadoc 文档都是基于网页格式的，打开是很方便，不过真的用的时候，搜索每个方法或者什么的就很麻烦了，而 chm 帮助文档格式不但文件小，查阅都很方便，所以网上就出现了很多把 Javadoc 转换为 chm 格式的帮助文档的软件 / 工具或者方法。

         自己最近需要真的需要这个方面的需求，查阅了网上很多方法，发现很多都是写的很不详细，对于我这种刚接触的很是不清楚，经过我的学习和理解，现提供从网上总结的 Javadoc 转换 chm 帮助文档的四种方法，详细提供各个转换的步骤供大家学习， 并且提供英文版本和中文版本 Javadoc 转换过程中出现的问题，特别是中文的时候出现的乱码现象，也提供一些解决方案 。

预处理

         转换之前需要了解的是 chm 是微软公司发布的一种帮助文档格式，所有，要使用下面的方法转换，请先安装 HTML Help Workshop （后面简称为 HHW ）（实际上后面的一些处理有些都是在上面操作的）

  http://msdn.microsoft.com/en-us/library/ms669985.aspx ，下载完毕后就是安装了，很简单。

       还有一个很重要的问题，就是如何把项目打成 Javadoc ，这有人应该会说，很简单啊，就是使用 Eclipse 或者 Myeclipse 的 Export 功能，是的，这是可以，但是有些小的方面还是需要我们强烈注意的

第一个问题就是 Java 代码的格式问题

       Java 代码编写的使用有的使用 GBK ，有的使用 UTF-8 ，这个时候就会有区别。使用 GBK 编码的时候生成 Javadoc 文档时没有太大问题的，但是，要是整个项目的默认编码格式是 UTF-8 的话，就会报 警告：编码 GBK 的不可映射字符

根本没有成功生成 Javadoc 文档，如何解决？解决方案就是在生成 Javadoc 的时候对 VM options 进行编码设置 -encoding UTF-8 -charset UTF-8 ，设置如下：

 

 

第二个问题就是如何把生成的 Javadoc 文档生成英语版本

         这个问题有的时候为了解决中文乱码是很重要的，我们生成英文版本的 Javadoc （仅对生成的 Javadoc 框架的语言做限制，并没有对注释内容的格式做限制，也就是说这个时候注释还是可以是中文的）。

         解决方案也是在 VM options 中加入 -locale en_US ，但是此时注意的是，如果把 -locale en_US 设置在后面的话，会报一个错误，大致是 -locale en_US 在 javadoc 命令必须是在最前面 ，所有，正确的写法就是 -locale en_US -encoding UTF-8 -charset UTF-8 （整合上面），默认如果不写 -locale 的话，安装 locale 语言来进行设置，当然我们中国人就是中文的了。（当然如果你工程默认编码是 GBK 而且您想生成中文的帮助文档的话，这写都可以不要，使用默认即可）

设置截图如下：

         做好了上面的工作，现在就请大家看我是如何转换成 chm 帮助文档的。

（做完这些，请生成中文和英文各一份 Javadoc 文档，供后面测试使用）

 

 

第一种：使用 jd2chm 来生成 chm 帮助文档

使用原版 jd2chm_exe_03 转换成 chm

原版 jd2chm_exe_03 需要通过官网下载 http://www.burgaud.com/jd2chm.html 不过现在我这是不可以访问的，只能通过代理来访问下载工具。（不要担心，最后我会把所有的工具打包供大家下载）。下载解压后就是一个 jd2chm.exe 文件，怎么使用？很简单，就是把这个文件放到需要生成 Javadoc 的目录下，必须保证同一个目录下一定要有 index.html ，不然不可生成，单击，或者在 cmd 命令中打开 exe ，填写 project name 和 title 即可。

生成英文版本如下

生成中文版本如下

 

 

上面整个生成都很 OK ，中英文支持都非常的好，唯一遗憾的是，工具生成的时候加了 About… 和没有顺便生成 .HHP, .HHK, .HHC 文件，有的时候 About 我们并不需要或者换成其他的，这个时候可以使用其他的 chm 编辑器或者 HHW 反编译修改后重新编译生成，具体操作请大家尝试。

使用网上高手改进的版本 jd2chm_0.34 转换成 chm

网上一个高手修改了一些很多有用的地方，如果想了解的话，请移步 http://download.csdn.net/source/1024968 查看并下载。

生成英文版本如下

请注意最后一个一定要选择 y ，意思就是在原 Javadoc 文档里修改一点东西（就我看，就是加了一个 about.html ），是否同意？不同意如何生成？

生成中文版本如下

 

 

比原版本的好处是不需在放到 Javadoc 目录下了，还可以使用最新的微软雅黑字体，而且能够生成 hhc 、 hhk 、 hhp 文件，方便我们使用 HHW 进行编辑。遗憾还是 about 并且有点破坏了原 Javadoc 文档（加了一个 about.html ），这个时候通过 HHW 工具很方便的进行编辑（有了 hhc 、 hhk 、 hhp 文件）。修改一份给大家看看，打开 hhp 文件，并打开 About… 文件，修改部分内容（就是一个 html 语言写的网页了）

修改完成后，保存并编译

 

 

对比下面修改后的 About

 

 

第二种：使用 javadoc2chm 来生成 chm 帮助文档

先下载工具 javadoc2chm-1.1.0.7.msi ，搜索下载（后面会提供），下载完成并安装，会在开始菜单里生成程序快捷方式。

生成英文版本如下

生成中文版本如下

 

 

界面操作，很方便，英文支持非常好，中文有一处乱码（上面目录第一层），几乎很完美，遗憾是 Title 后面加了 -Generated by javadoc2chm 和中文有点乱码，没有生成 hhc 、 hhk 、 hhp 文件 ( 实际上在转换的时候是生成的这三个文件，后面被删除了，如果耍点小聪明的话，可以在生成过程中复制一份，如果速度快的话，会提示文件已经被删除，是否重试，这个时候再转换，看文件生成后点重试即可得到这三个文件，不要反编译多好 ) ，这种方法建议使用英文版本。

自己修改了一份中文版本的转换，现提供部分步骤

 

 

 

 

看看修改后的效果吧

第一次打开的首页

个性化设置：加入 Blog ，请大家有空多踩踩我的博客： http://blog.sina.com.cn/usc3l

 

 

 

 

上面的两种方法也是我极力推荐大家使用 的，下面的两种方法仅供学习，里面有很多问题，中文乱码什么的，都会出现。

 

 

第三种：使用 javadoc2help 来生成 chm 帮助文档

官方网站 http://javadoc2help.sourceforge.net/ ，下载解压即可，里面最重要的就是 lib 目录下面的 Javadoc2Help.jar ，注意我们就是使用这个 jar 文件进行生成。官网上也提供了如何使用。

生成英文版本如下

Cmd 命令进入 jar 文件目录，写下面的命令回车

java -jar Javadoc2Help.jar -chm -src f:/docs/api_en_US -dest f:/docs/api_en_US2

（具体路径请根据需要修改）

注意： -dest 后面的目录请不要写原目录，不然生成不了 chm 并且覆盖了原目录文件。

 

 

生成中文版本如下

Cmd 命令进入 jar 文件目录，写下面的命令回车

java -jar Javadoc2Help.jar -chm -src f:/docs/api_zh_CN -dest f:/docs/api_zh_CN2

（具体路径请根据需要修改）

注意： -dest 后面的目录请不要写原目录，不然生成不了 chm 并且覆盖了原目录文件。

 

 

基本能够完成转换，但是不了建立索引，不能设置 Title 和文件名，对中文严重不支持不管是英文版本还是中文版本的 chm 都出现了中文乱码现象，还有 chm 文件就是便于查询，竟然不能生产索引，建议不使用。

 

 

第四种：使用 google code 里面的 javadoc2chm 项目构建

请参考 http://code.google.com/p/javadoc2chm/ 下载 ruby 和 javadoc2chm-0.1.zip 等必要步骤。

Google code 上页介绍了如何使用，解压压缩包。使用这个，就必须先安装 ruby 和 HHW 。

生成英文版本如下

Cmd 命令进入 javadoc2chm 目录，写下面的命令

ruby createhhp.rb api_en_US f:/docs/api_en_US 回车

"C:/Program Files/HTML Help Workshop/hhc.exe" api_en_US.hhp 回车

（注意 C:/Program Files/HTML Help Workshop/hhc.exe 是 HHW 默认安装路径，如果不是请自行修改）

生成的 chm 文件在解压的包的文件夹里：

打开后是上面的这样子，具体的原因不清楚，不过解决的方法就是把 Javadoc 文件夹和 ruby 命令的文件夹不要放在同一个盘内，不在同一个盘里就会使用绝对路径。重修生成，但是这种方法也并不适合，当我们把原 Javadoc 文档的文件夹删除或者移动了，这个时候也会出现上面的情况。具体的我打开了 hhp 文件查看了一下，应该是这种方法使用的是觉得路径，而并没有把文件进行包装在生成。（要查看下面截图的效果，请把 docs 文件夹保留）

命令

ruby createhhp.rb api_en_US e:/docs/api_en_US

"C:/Program Files/HTML Help Workshop/hhc.exe" api_en_US.hhp

 

 

生成中文版本如下

Cmd 命令进入 javadoc2chm 目录，写下面的命令

ruby createhhp.rb 中文帮助文档 e:/docs/api_zh_CN 回车

"C:/Program Files/HTML Help Workshop/hhc.exe" 中文帮助文档 .hhp 回车

（注意 C:/Program Files/HTML Help Workshop/hhc.exe 是 HHW 默认安装路径，如果不是请自行修改）

不能设置 Title 和中文的 Title 时候乱码，操作麻烦，还要安装 ruby 辅助软件。

 

 

 

 

 

 

 

 

总结

上面的一些不完美的地方，都可以使用 HTML Help Workshop 进行改善。实际上也是因为此次机遇，让我学习了 HTML Help Workshop 的操作，以后制作 chm 文档就很方便了。

上面方法通过参考网上的操作总结自己亲自实际而成，需要探讨的请联系 QQ ： 506817493 。

 

 

顺利提高所有工具和制作成果的文件下载 ( 不包括 ruby 辅助软件，自行下载 )

Javadoc 转换 chm 帮助文档的四种方法总结 .rar