`
444878909
  • 浏览: 631585 次
文章分类
社区版块
存档分类
最新评论

JAVA eclipse(myeclipse)生成帮助文档(html或chm格式)

 
阅读更多

目录(?)[+]

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

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

V1.0


关键词

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或者MyeclipseExport功能,是的,这是可以,但是有些小的方面还是需要我们强烈注意的

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

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

clip_image002

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

clip_image004

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

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

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

设置截图如下:

clip_image006

做好了上面的工作,现在就请大家看我是如何转换成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即可。

生成英文版本如下

clip_image008

clip_image010

生成中文版本如下

clip_image012

clip_image014

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


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

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

生成英文版本如下

clip_image016

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

clip_image018

clip_image020

生成中文版本如下

clip_image022

clip_image024

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

修改完成后,保存并编译

clip_image026

clip_image027

对比下面修改后的About

clip_image028


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

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

生成英文版本如下

clip_image029

clip_image031

生成中文版本如下

clip_image032clip_image034

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

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

clip_image036

clip_image038clip_image040

clip_image041

clip_image043

看看修改后的效果吧

第一次打开的首页

clip_image045

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

clip_image047

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


第三种:使用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

(具体路径请根据需要修改)

clip_image049

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

clip_image051

生成中文版本如下

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

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

(具体路径请根据需要修改)

clip_image053

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

clip_image055

基本能够完成转换,但是不了建立索引,不能设置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默认安装路径,如果不是请自行修改)

clip_image057

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

clip_image059

clip_image061

打开后是上面的这样子,具体的原因不清楚,不过解决的方法就是把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

clip_image063

生成中文版本如下

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默认安装路径,如果不是请自行修改)

clip_image065clip_image067clip_image069

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

总结

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

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

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

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

clip_image070

分享到:
评论

相关推荐

Global site tag (gtag.js) - Google Analytics