Javadoc转换chm帮助文档的四种方法总结(转)
朋友,当您在一个项目完成后,是不是需要把你的源码打包并且把注释打成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
转载自(http://www.blogjava.net/lishunli/archive/2010/01/07/308618.html)