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

转载 2013年12月03日 23:18:47

关键词
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转换chm帮助文档的四种方法总结
根本没有成功生成Javadoc文档,如何解决?解决方案就是在生成Javadoc的时候对VM options进行编码设置-encoding UTF-8 -charset UTF-8,设置如下:

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

第二个问题就是如何把生成的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而且您想生成中文的帮助文档的话,这写都可以不要,使用默认即可)
设置截图如下:
 Javadoc转换chm帮助文档的四种方法总结
 做好了上面的工作,现在就请大家看我是如何转换成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即可。
生成英文版本如下
 Javadoc转换chm帮助文档的四种方法总结

Javadoc转换chm帮助文档的四种方法总结
 
生成中文版本如下

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


 Javadoc转换chm帮助文档的四种方法总结
上面整个生成都很OK,中英文支持都非常的好,唯一遗憾的是,工具生成的时候加了About…和没有顺便生成.HHP, .HHK, .HHC文件,有的时候About我们并不需要或者换成其他的,这个时候可以使用其他的chm编辑器或者HHW 反编译修改后重新编译生成,具体操作请大家尝试。
 
使用网上高手改进的版本jd2chm_0.34转换成chm
网上一个高手修改了一些很多有用的地方,如果想了解的话,请移步http://download.csdn.net/source/1024968查看并下载。
生成英文版本如下
 Javadoc转换chm帮助文档的四种方法总结


请注意最后一个一定要选择y,意思就是在原Javadoc文档里修改一点东西(就我看,就是加了一个about.html),是否同意?不同意如何生成?Javadoc转换chm帮助文档的四种方法总结
 Javadoc转换chm帮助文档的四种方法总结
 
生成中文版本如下

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

Javadoc转换chm帮助文档的四种方法总结Javadoc转换chm帮助文档的四种方法总结
对比下面修改后的About

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


第二种:使用javadoc2chm来生成chm帮助文档
先下载工具javadoc2chm-1.1.0.7.msi,搜索下载(后面会提供),下载完成并安装,会在开始菜单里生成程序快捷方式。
生成英文版本如下
 Javadoc转换chm帮助文档的四种方法总结Javadoc转换chm帮助文档的四种方法总结
 
生成中文版本如下

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

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

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

看看修改后的效果吧
第一次打开的首页

Javadoc转换chm帮助文档的四种方法总结
 
个性化设置:加入Blog,请大家有空多踩踩我的博客:http://blog.sina.com.cn/usc3l
Javadoc转换chm帮助文档的四种方法总结


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


第三种:使用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
(具体路径请根据需要修改)
 Javadoc转换chm帮助文档的四种方法总结
注意:-dest后面的目录请不要写原目录,不然生成不了chm并且覆盖了原目录文件。


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

生成中文版本如下
Cmd命令进入jar文件目录,写下面的命令回车
java -jar Javadoc2Help.jar -chm -src f:\docs\api_zh_CN -dest f:\docs\api_zh_CN2
(具体路径请根据需要修改)
 Javadoc转换chm帮助文档的四种方法总结
注意:-dest后面的目录请不要写原目录,不然生成不了chm并且覆盖了原目录文件。

Javadoc转换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默认安装路径,如果不是请自行修改)
 Javadoc转换chm帮助文档的四种方法总结
生成的chm文件在解压的包的文件夹里:

Javadoc转换chm帮助文档的四种方法总结
 Javadoc转换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
Javadoc转换chm帮助文档的四种方法总结

生成中文版本如下
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默认安装路径,如果不是请自行修改)

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

Javadoc转换chm帮助文档的四种方法总结
  Javadoc转换chm帮助文档的四种方法总结
不能设置Title和中文的Title时候乱码,操作麻烦,还要安装ruby辅助软件。

 


总结
上面的一些不完美的地方,都可以使用HTML Help Workshop进行改善。实际上也是因为此次机遇,让我学习了HTML Help Workshop的操作,以后制作chm文档就很方便了。还有,再说一下,极力推荐大家根据情况使用第一和第二种方法,尽量不要使用第三第四种方法。
上面方法通过参考网上的操作总结自己亲自实际而成,需要探讨的请联系QQ:506817493。

相关文章推荐

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

转自: http://lishunli.iteye.com/blog/1051688 Javadoc转换chm帮助文档的四种方法总结                              ...

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

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

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

朋友,当您在一个项目完成后,是不是需要把你的源码打包并且把注释打成Javadoc交给客户,Eclipse或者MyEclipse自动打成的Javadoc文档都是基于网页格式的,打开是很方便,不过真的用的...

javadoc转换chm帮助文档

  • 2014年09月01日 15:06
  • 14.78MB
  • 下载

在线帮助文档转CHM方法

在线帮助文档转CHM方法 用到的工具:       wget工具(Linux自带,Windows下请自行下载),htm2chm(共享软件,不过没什么限制) 具体步骤: 1、使用...
  • scmrpu
  • scmrpu
  • 2017年03月15日 13:48
  • 391

web工程生成javadoc帮助文档方法

Javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Java...

将oracle数据库表结构导出chm帮助文档

先来个效果图:总体分两步:1、通过powerdesigner将数据库导出html文件。2、使用一个小工具(Easy CHM)将htm转换成chm。下面详细说明:1、得到数据库表设计的pdm数据表结构(...

使用HTML HELP WORKSHOP制作CHM帮助文档

 制作chm电子书完美详解   2 3 4 5 6 7 分步阅读 Microsoft开发的制...

将oracle数据库表结构导出chm帮助文档

总体分两步: 1、通过powerdesigner将数据库导出html文件。 2、使用一个小工具(htm2chm)将htm转换成chm。 下面详细说明:   1、打开powerdesigner,点击da...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Javadoc转换chm帮助文档的四种方法总结
举报原因:
原因补充:

(最多只允许输入30个字)