Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié)

                                                                                                       V1.0

目錄

關(guān)鍵詞... 1

前言... 1

預(yù)處理... 1

第一種：使用jd2chm來(lái)生成chm幫助文檔... 4

使用原版jd2chm_exe_03轉(zhuǎn)換成chm.. 4

生成英文版本如下... 4

生成中文版本如下... 5

使用網(wǎng)上高手改進(jìn)的版本jd2chm_0.34轉(zhuǎn)換成chm.. 7

生成英文版本如下... 7

生成中文版本如下... 8

第二種：使用javadoc2chm來(lái)生成chm幫助文檔... 11

生成英文版本如下... 11

生成中文版本如下... 12

第三種：使用javadoc2help來(lái)生成chm幫助文檔... 18

生成英文版本如下... 18

生成中文版本如下... 18

第四種：使用google code里面的javadoc2chm項(xiàng)目構(gòu)建... 20

生成英文版本如下... 20

生成中文版本如下... 22

總結(jié)... 23

關(guān)鍵詞

Javadoc chm 轉(zhuǎn)換 jd2chm javadoc2chm javadoc2help Javadoc2chm 中文亂碼 李順利

前言

         朋友，當(dāng)您在一個(gè)項(xiàng)目完成后，是不是需要把你的源碼打包并且把注釋打成Javadoc交給客戶，Eclipse或者MyEclipse自動(dòng)打成的Javadoc文檔都是基于網(wǎng)頁(yè)格式的，打開(kāi)是很方便，不過(guò)真的用的時(shí)候，搜索每個(gè)方法或者什么的就很麻煩了，而chm幫助文檔格式不但文件小，查閱都很方便，所以網(wǎng)上就出現(xiàn)了很多把Javadoc轉(zhuǎn)換為chm格式的幫助文檔的軟件/工具或者方法。

         自己最近需要真的需要這個(gè)方面的需求，查閱了網(wǎng)上很多方法，發(fā)現(xiàn)很多都是寫(xiě)的很不詳細(xì)，對(duì)于我這種剛接觸的很是不清楚，經(jīng)過(guò)我的學(xué)習(xí)和理解，現(xiàn)提供從網(wǎng)上總結(jié)的Javadoc轉(zhuǎn)換chm幫助文檔的四種方法，詳細(xì)提供各個(gè)轉(zhuǎn)換的步驟供大家學(xué)習(xí)，并且提供英文版本和中文版本Javadoc轉(zhuǎn)換過(guò)程中出現(xiàn)的問(wèn)題，特別是中文的時(shí)候出現(xiàn)的亂碼現(xiàn)象，也提供一些解決方案。

預(yù)處理

         轉(zhuǎn)換之前需要了解的是chm是微軟公司發(fā)布的一種幫助文檔格式，所有，要使用下面的方法轉(zhuǎn)換，請(qǐng)先安裝HTML Help Workshop（后面簡(jiǎn)稱為HHW）（實(shí)際上后面的一些處理有些都是在上面操作的）

 http://msdn.microsoft.com/en-us/library/ms669985.aspx，下載完畢后就是安裝了，很簡(jiǎn)單。

       還有一個(gè)很重要的問(wèn)題，就是如何把項(xiàng)目打成Javadoc，這有人應(yīng)該會(huì)說(shuō)，很簡(jiǎn)單啊，就是使用Eclipse或者Myeclipse的Export功能，是的，這是可以，但是有些小的方面還是需要我們強(qiáng)烈注意的

第一個(gè)問(wèn)題就是Java代碼的格式問(wèn)題

       Java代碼編寫(xiě)的使用有的使用GBK，有的使用UTF-8，這個(gè)時(shí)候就會(huì)有區(qū)別。使用GBK編碼的時(shí)候生成Javadoc文檔時(shí)沒(méi)有太大問(wèn)題的，但是，要是整個(gè)項(xiàng)目的默認(rèn)編碼格式是UTF-8的話，就會(huì)報(bào)警告：編碼 GBK 的不可映射字符

根本沒(méi)有成功生成Javadoc文檔，如何解決？解決方案就是在生成Javadoc的時(shí)候?qū)?/span>VM options進(jìn)行編碼設(shè)置-encoding UTF-8 -charset UTF-8，設(shè)置如下：

第二個(gè)問(wèn)題就是如何把生成的Javadoc文檔生成英語(yǔ)版本

         這個(gè)問(wèn)題有的時(shí)候?yàn)榱私鉀Q中文亂碼是很重要的，我們生成英文版本的Javadoc（僅對(duì)生成的Javadoc框架的語(yǔ)言做限制，并沒(méi)有對(duì)注釋內(nèi)容的格式做限制，也就是說(shuō)這個(gè)時(shí)候注釋還是可以是中文的）。

         解決方案也是在VM options中加入-locale en_US，但是此時(shí)注意的是，如果把-locale en_US設(shè)置在后面的話，會(huì)報(bào)一個(gè)錯(cuò)誤，大致是-locale en_US 在javadoc命令必須是在最前面，所有，正確的寫(xiě)法就是-locale en_US -encoding UTF-8 -charset UTF-8（整合上面），默認(rèn)如果不寫(xiě)-locale的話，安裝locale語(yǔ)言來(lái)進(jìn)行設(shè)置，當(dāng)然我們中國(guó)人就是中文的了。（當(dāng)然如果你工程默認(rèn)編碼是GBK而且您想生成中文的幫助文檔的話，這寫(xiě)都可以不要，使用默認(rèn)即可）

設(shè)置截圖如下：

         做好了上面的工作，現(xiàn)在就請(qǐng)大家看我是如何轉(zhuǎn)換成chm幫助文檔的。

（做完這些，請(qǐng)生成中文和英文各一份Javadoc文檔，供后面測(cè)試使用）

第一種：使用jd2chm來(lái)生成chm幫助文檔

使用原版jd2chm_exe_03轉(zhuǎn)換成chm

原版jd2chm_exe_03需要通過(guò)官網(wǎng)下載http://www.burgaud.com/jd2chm.html不過(guò)現(xiàn)在我這是不可以訪問(wèn)的，只能通過(guò)代理來(lái)訪問(wèn)下載工具。（不要擔(dān)心，最后我會(huì)把所有的工具打包供大家下載）。下載解壓后就是一個(gè)jd2chm.exe文件，怎么使用？很簡(jiǎn)單，就是把這個(gè)文件放到需要生成Javadoc的目錄下，必須保證同一個(gè)目錄下一定要有index.html，不然不可生成，單擊，或者在cmd命令中打開(kāi)exe，填寫(xiě)project name和title即可。

生成英文版本如下

生成中文版本如下

上面整個(gè)生成都很OK，中英文支持都非常的好，唯一遺憾的是，工具生成的時(shí)候加了About…和沒(méi)有順便生成.HHP, .HHK, .HHC文件，有的時(shí)候About我們并不需要或者換成其他的，這個(gè)時(shí)候可以使用其他的chm編輯器或者HHW 反編譯修改后重新編譯生成，具體操作請(qǐng)大家嘗試。

使用網(wǎng)上高手改進(jìn)的版本jd2chm_0.34轉(zhuǎn)換成chm

網(wǎng)上一個(gè)高手修改了一些很多有用的地方，如果想了解的話，請(qǐng)移步http://download.csdn.net/source/1024968查看并下載。

生成英文版本如下

請(qǐng)注意最后一個(gè)一定要選擇y，意思就是在原Javadoc文檔里修改一點(diǎn)東西（就我看，就是加了一個(gè)about.html），是否同意？不同意如何生成？

生成中文版本如下

比原版本的好處是不需在放到Javadoc目錄下了，還可以使用最新的微軟雅黑字體，而且能夠生成hhc、hhk、hhp文件，方便我們使用HHW進(jìn)行編輯。遺憾還是about并且有點(diǎn)破壞了原Javadoc文檔（加了一個(gè)about.html），這個(gè)時(shí)候通過(guò)HHW工具很方便的進(jìn)行編輯（有了hhc、hhk、hhp文件）。修改一份給大家看看，打開(kāi)hhp文件，并打開(kāi)About…文件，修改部分內(nèi)容（就是一個(gè)html語(yǔ)言寫(xiě)的網(wǎng)頁(yè)了）

修改完成后，保存并編譯

對(duì)比下面修改后的About

第二種：使用javadoc2chm來(lái)生成chm幫助文檔

先下載工具javadoc2chm-1.1.0.7.msi，搜索下載（后面會(huì)提供），下載完成并安裝，會(huì)在開(kāi)始菜單里生成程序快捷方式。

生成英文版本如下

生成中文版本如下

界面操作，很方便，英文支持非常好，中文有一處亂碼（上面目錄第一層），幾乎很完美，遺憾是Title后面加了-Generated by javadoc2chm和中文有點(diǎn)亂碼，沒(méi)有生成hhc、hhk、hhp文件(實(shí)際上在轉(zhuǎn)換的時(shí)候是生成的這三個(gè)文件，后面被刪除了，如果耍點(diǎn)小聰明的話，可以在生成過(guò)程中復(fù)制一份，如果速度快的話，會(huì)提示文件已經(jīng)被刪除，是否重試，這個(gè)時(shí)候再轉(zhuǎn)換，看文件生成后點(diǎn)重試即可得到這三個(gè)文件，不要反編譯多好)，這種方法建議使用英文版本。

自己修改了一份中文版本的轉(zhuǎn)換，現(xiàn)提供部分步驟

看看修改后的效果吧

第一次打開(kāi)的首頁(yè)

個(gè)性化設(shè)置：加入Blog，請(qǐng)大家有空多踩踩我的博客：http://blog.sina.com.cn/usc3l

上面的兩種方法也是我極力推薦大家使用的，下面的兩種方法僅供學(xué)習(xí)，里面有很多問(wèn)題，中文亂碼什么的，都會(huì)出現(xiàn)。

第三種：使用javadoc2help來(lái)生成chm幫助文檔

官方網(wǎng)站http://javadoc2help.sourceforge.net/，下載解壓即可，里面最重要的就是lib目錄下面的Javadoc2Help.jar，注意我們就是使用這個(gè)jar文件進(jìn)行生成。官網(wǎng)上也提供了如何使用。

生成英文版本如下

Cmd命令進(jìn)入jar文件目錄，寫(xiě)下面的命令回車

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

（具體路徑請(qǐng)根據(jù)需要修改）

注意：-dest后面的目錄請(qǐng)不要寫(xiě)原目錄，不然生成不了chm并且覆蓋了原目錄文件。

生成中文版本如下

Cmd命令進(jìn)入jar文件目錄，寫(xiě)下面的命令回車

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

（具體路徑請(qǐng)根據(jù)需要修改）

注意：-dest后面的目錄請(qǐng)不要寫(xiě)原目錄，不然生成不了chm并且覆蓋了原目錄文件。

基本能夠完成轉(zhuǎn)換，但是不了建立索引，不能設(shè)置Title和文件名，對(duì)中文嚴(yán)重不支持不管是英文版本還是中文版本的chm都出現(xiàn)了中文亂碼現(xiàn)象，還有chm文件就是便于查詢，竟然不能生產(chǎn)索引，建議不使用。

第四種：使用google code里面的javadoc2chm項(xiàng)目構(gòu)建

請(qǐng)參考http://code.google.com/p/javadoc2chm/下載ruby和javadoc2chm-0.1.zip等必要步驟。

Google code上頁(yè)介紹了如何使用，解壓壓縮包。使用這個(gè)，就必須先安裝ruby和HHW。

生成英文版本如下

Cmd命令進(jìn)入javadoc2chm目錄，寫(xiě)下面的命令

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默認(rèn)安裝路徑，如果不是請(qǐng)自行修改）

生成的chm文件在解壓的包的文件夾里：

打開(kāi)后是上面的這樣子，具體的原因不清楚，不過(guò)解決的方法就是把Javadoc文件夾和ruby命令的文件夾不要放在同一個(gè)盤(pán)內(nèi)，不在同一個(gè)盤(pán)里就會(huì)使用絕對(duì)路徑。重修生成，但是這種方法也并不適合，當(dāng)我們把原Javadoc文檔的文件夾刪除或者移動(dòng)了，這個(gè)時(shí)候也會(huì)出現(xiàn)上面的情況。具體的我打開(kāi)了hhp文件查看了一下，應(yīng)該是這種方法使用的是覺(jué)得路徑，而并沒(méi)有把文件進(jìn)行包裝在生成。（要查看下面截圖的效果，請(qǐng)把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命令進(jìn)入javadoc2chm目錄，寫(xiě)下面的命令

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默認(rèn)安裝路徑，如果不是請(qǐng)自行修改）

不能設(shè)置Title和中文的Title時(shí)候亂碼，操作麻煩，還要安裝ruby輔助軟件。

總結(jié)

上面的一些不完美的地方，都可以使用HTML Help Workshop進(jìn)行改善。實(shí)際上也是因?yàn)榇舜螜C(jī)遇，讓我學(xué)習(xí)了HTML Help Workshop的操作，以后制作chm文檔就很方便了。

上面方法通過(guò)參考網(wǎng)上的操作總結(jié)自己親自實(shí)際而成，需要探討的請(qǐng)聯(lián)系QQ：506817493。

順利提高所有工具和制作成果的文件下載(不包括ruby輔助軟件，自行下載)

Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié).rar

順利寫(xiě)于2010年1月6日