Javadoc chm 帮助文档生成策略

Javadoc chm 帮助文档生成策略

 

1. 解决方案

 

Java没有直接生成.chm帮助文档的办法，Java的帮助文档都是原生的Javadoc文档，

Javadoc 文档都是基于网页格式的，打开很方便，不过搜索方法或者类什么的就很麻烦，

而 chm 帮助文档格式不但文件小，搜索尤其强大，所以我们的解决办法就是：

 

a) 首先生成 Java doc 文档。

b) 再将 Java doc 文档转换成 chm 文档。

 

2. 工欲善其事，必先利其器。环境搭建

 

a) Java 环境搭建：

能看到这里的，相信这个都会。实在不会的朋友，请查阅我的这方面文档，或者去

网上查阅解决办法，这里不再赘述。

 

b) HTML Help Workshop（简称为 HHW）搭建：

.chm 是微软公司发布的一种帮助文档格式，所以必先安装此环境。打开微软官方

网站：http://msdn.microsoft.com/en-us/library/ms669985.aspx。下载完

毕后（htmlhelp.exe）并安装就行。

 

3. Java doc 文档生成

 

a) 生成方法

 

    i.   使用原生的 Java doc 指令

         虽然这个比较“纯”，但并不是我推荐的，对于现在快节奏生活的我们，去命

         令行去敲打指令，何其麻烦，还易错，除非没有其他的解决方案。

 

    ii.   使用 eclipse 或者 myeclipse 的 Java doc 指令

          这个方法是我比较推荐的，毕竟我相信绝大多数的项目都是在这 2 个 IDE 的

          环境下开发出来的，而且操作简单。

          1） 项目右键 Export --> Java -->Javadoc，

                如下图：

 

                大图如下：

 

             2） 点击 Next，下一步。如下图：

 

          3） 或者选中项目，点击 eclipse 或者 myeclipse 的工具栏 Project -->

                Generate Javadoc，一样可以到达上图界面，其实我们不能看出，我们

                的 IDE 还是调用了 jdk 的 javadoc.exe。

 

          4） 点击 Next，下一步。如下图：

 

                填写好 title，选中全部依赖的 jar，如果你在上面的步骤修改了 doc 的生

                成目录，请不要选中这里面的目录，如图所示：

 

 

          5） 点击 Next，下一步。如下图：

                选择好 JRE 的版本，并且填写编码格式。

 

          6） 点击 Finish，稍等片刻，如下图：

 

          7） 控制台出现如上图界面，恭喜你，Javadoc 生成成功。

 

     iii.  其他方法或者其他 IDE

          精力有限，还不了解，知道有更好办法的朋友，麻烦告诉下，共同进步嘛。

 

b) 注意事项（相对生成过程中）

 

    i.   Use standard doclet，修改 Java doc 文档的输出目录。

 

    ii.   如果修改了 Java doc 文档的输出目录，请不要 select 原来的目录。

 

    iii.  编码问题。

         这个看项目的编码，一定要你的项目编码和 Javadoc 生成时候的编码一致，

         所以才有了-encoding UTF-8 -charset UTF-8 这样的配置。如果你的项目

         是 GBK 就把 UTF-8 换掉就是，我的项目是 UTF-8 的编码，否则择出现如下

         的错误：

 

c) 题外话

 

    i.   规范真的重要性

         把项目打成 Java doc 文档，本来很简单的过程，却因为各种各样的原因，使

         得开发和编写代码不正规，而造成各种各样的问题，这里再次提醒广大朋友们，

         良好的编程习惯真的可以为我们节约很多时间。

 

    ii.  开发环境的重要性

        在我个人认为，自己的开发环境，特别是 IDE 的配置，尤其重要，很多项目

        的编码是 GBK，打包的时候又用 UTF-8，真的很容易出错，各种乱码。

 

d) Java doc 的国际化生成

 

    i.   其实生成的时候“-locale zh_CN”，就是国家化指令。

         默认如果不写-locale 的话，安装 locale 语言来进行设置，当然我们中国人就

         是中文的了（例如英文的：-locale en_US）。其他的都一样的道理，但是如

         果 locale 语言没有你需要的，会自动以英文来替代。

 

4. Java doc 转换成 chm

 

a) 使用 jd2chm 来生成 chm 帮助文档

 

这种方式是最推荐的，使用原版 jd2chm_exe_03 转换成 chm，原版需要通过官

网下载 http://www.burgaud.com/jd2chm.html 。可惜这个网址已经被和掉了，

那么大家就出去吧，呵呵，怎么出去？大家都懂的。

 

     i.   jd2chm_exe_03.zip 下载后如下图显示：

 

     ii.  使用方法：

          就是把这个文件放到需要生成 Javadoc 的目录下，必须保证同一个目录下一

          定要有 index.html，不然不可生成。单击，或者在 cmd 命令中打开 exe，

          填写 project name 和 title 即可。如下图：

 

         上面整个生成都很 OK，中英文支持都非常的好，唯一遗憾的是，工具生成的

         时候加了About…和没有顺便生成.HHP, .HHK, .HHC文件，有的时候About

         我们并不需要或者换成其他的，这个时候可以使用其他的 chm 编辑器或者

         HHW 反编译修改后重新编译生成，具体操作请大家尝试。

 

b) 使用网上高手改进的版本 jd2chm_0.34 来生成 chm 帮助文档

网上一个高手修改了一些很多有用的地方，如果想了解的话，请移步

http://download.csdn.net/detail/xxli79/1024968 查看并下载。

 

      i.   下载后如图：

 

      ii.   使用方法

            直接双击 jd2chm.exe 运行，输入相关内容，如下图所示：

 

            比原版本的好处是不需在放到 Javadoc 目录下了，还可以使用最新的微软雅

            黑字体，而且能够生成 hhc、hhk、hhp 文件，方便我们使用 HHW 进行编辑。

            遗憾还是 about 并且有点破坏了原 Javadoc 文档（加了一个 about.html），

            这个时候通过 HHW 工具很方便的进行编辑（有了 hhc、hhk、hhp 文件）。

            可以修改，打开 hhp 文件，并打开 About…文件，修改部分内容（就是一个

            html 语言写的网页了）。

 

c) 使用 javadoc2chm 来生成 chm 帮助文档

 

    i.   下载地址：http://jan.baresovi.cz/dr/en/javadoc-chm，如下图所示：

         安装好。

 

    ii.  使用方法

         直接运行 javadoc2chm.exe，填写好相关信息，点击 Go，如下图所示：

 

         界面操作，很方便，英文支持非常好，中文有一处乱码（上面目录第一层），

         几乎很完美，遗憾是 Title 后面加了-Generated by javadoc2chm 和中文

         有点乱码，没有生成 hhc、hhk、hhp 文件(实际上在转换的时候是生成的这

         三个文件，后面被删除了，如果耍点小聪明的话，可以在生成过程中复制一份，

         如果速度快的话，会提示文件已经被删除，是否重试，这个时候再转换，看文

         件生成后点重试即可得到这三个文件，不要反编译多好)，这种方法建议使用

         英文版本。

 

         乱码那些可用 HTML Help Workshop 来修改。

 

d) 使用 javadoc2help 来生成 chm 帮助文档

 

e) 使用 google code 里面的 javadoc2chm 项目构建

 

5. 总结：

由于时间问题我就只写了 2 中转换方式，其实也足够用了。剩下的 2 种我会找时间来总

结的，这里偷个懒。上面不完善的地方，其实都可以使用 HTML Help Workshop 编辑

器来修改，大家有兴趣的话，可以去学习下 HTML Help Workshop 的使用方法，对于

以后的 chm 文档管理也是好的。

 

6. 参考文献：

http://www.blogjava.net/lishunli/archive/2010/01/07/308618.html

http://www.blogjava.net/lishunli/archive/2010/01/12/309218.html