|
Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié) V1.0 目錄 使用原版jd2chm_exe_03轉(zhuǎn)換成chm.. 4 使用網(wǎng)上高手改進(jìn)的版本jd2chm_0.34轉(zhuǎn)換成chm.. 7 第二種：使用javadoc2chm來生成chm幫助文檔... 11 第三種：使用javadoc2help來生成chm幫助文檔... 18 第四種：使用google code里面的javadoc2chm項目構(gòu)建... 20
關(guān)鍵詞
Javadoc chm 轉(zhuǎn)換 jd2chm javadoc2chm javadoc2help Javadoc2chm 中文亂碼 李順利 前言
朋友，當(dāng)您在一個項目完成后,，是不是需要把你的源碼打包并且把注釋打成Javadoc交給客戶,，Eclipse或者MyEclipse自動打成的Javadoc文檔都是基于網(wǎng)頁格式的，打開是很方便,，不過真的用的時候,，搜索每個方法或者什么的就很麻煩了，而chm幫助文檔格式不但文件小,，查閱都很方便,，所以網(wǎng)上就出現(xiàn)了很多把Javadoc轉(zhuǎn)換為chm格式的幫助文檔的軟件/工具或者方法。 自己最近需要真的需要這個方面的需求,，查閱了網(wǎng)上很多方法,，發(fā)現(xiàn)很多都是寫的很不詳細(xì)，對于我這種剛接觸的很是不清楚,，經(jīng)過我的學(xué)習(xí)和理解,，現(xiàn)提供從網(wǎng)上總結(jié)的Javadoc轉(zhuǎn)換chm幫助文檔的四種方法，詳細(xì)提供各個轉(zhuǎn)換的步驟供大家學(xué)習(xí),，并且提供英文版本和中文版本Javadoc轉(zhuǎn)換過程中出現(xiàn)的問題,，特別是中文的時候出現(xiàn)的亂碼現(xiàn)象，也提供一些解決方案,。 預(yù)處理
轉(zhuǎn)換之前需要了解的是chm是微軟公司發(fā)布的一種幫助文檔格式,，所有，要使用下面的方法轉(zhuǎn)換,，請先安裝HTML Help Workshop（后面簡稱為HHW）（實際上后面的一些處理有些都是在上面操作的） http://msdn.microsoft.com/en-us/library/ms669985.aspx,，下載完畢后就是安裝了，很簡單,。 還有一個很重要的問題,，就是如何把項目打成Javadoc，這有人應(yīng)該會說,，很簡單啊,，就是使用Eclipse或者Myeclipse的Export功能，是的,，這是可以,，但是有些小的方面還是需要我們強烈注意的 第一個問題就是Java代碼的格式問題 Java代碼編寫的使用有的使用GBK，有的使用UTF-8，這個時候就會有區(qū)別,。使用GBK編碼的時候生成Javadoc文檔時沒有太大問題的,，但是，要是整個項目的默認(rèn)編碼格式是UTF-8的話,，就會報警告：編碼 GBK 的不可映射字符
根本沒有成功生成Javadoc文檔,，如何解決？解決方案就是在生成Javadoc的時候?qū)?/span>VM options進(jìn)行編碼設(shè)置-encoding UTF-8 -charset UTF-8,，設(shè)置如下：
第二個問題就是如何把生成的Javadoc文檔生成英語版本 這個問題有的時候為了解決中文亂碼是很重要的,，我們生成英文版本的Javadoc（僅對生成的Javadoc框架的語言做限制，并沒有對注釋內(nèi)容的格式做限制,，也就是說這個時候注釋還是可以是中文的）。 解決方案也是在VM options中加入-locale en_US,，但是此時注意的是,，如果把-locale en_US設(shè)置在后面的話，會報一個錯誤,，大致是-locale en_US 在javadoc命令必須是在最前面,，所有，正確的寫法就是-locale en_US -encoding UTF-8 -charset UTF-8（整合上面）,，默認(rèn)如果不寫-locale的話,，安裝locale語言來進(jìn)行設(shè)置，當(dāng)然我們中國人就是中文的了,。（當(dāng)然如果你工程默認(rèn)編碼是GBK而且您想生成中文的幫助文檔的話,，這寫都可以不要，使用默認(rèn)即可） 設(shè)置截圖如下：
做好了上面的工作,，現(xiàn)在就請大家看我是如何轉(zhuǎn)換成chm幫助文檔的,。 （做完這些，請生成中文和英文各一份Javadoc文檔,，供后面測試使用） 第一種：使用jd2chm來生成chm幫助文檔
使用原版jd2chm_exe_03轉(zhuǎn)換成chm
原版jd2chm_exe_03需要通過官網(wǎng)下載http://www./jd2chm.html不過現(xiàn)在我這是不可以訪問的,，只能通過代理來訪問下載工具。（不要擔(dān)心,，最后我會把所有的工具打包供大家下載）,。下載解壓后就是一個jd2chm.exe文件，怎么使用,？很簡單,，就是把這個文件放到需要生成Javadoc的目錄下，必須保證同一個目錄下一定要有index.html,，不然不可生成,，單擊，或者在cmd命令中打開exe,，填寫project name和title即可,。 生成英文版本如下
生成中文版本如下
上面整個生成都很OK,，中英文支持都非常的好，唯一遺憾的是,，工具生成的時候加了About…和沒有順便生成.HHP, .HHK, .HHC文件,，有的時候About我們并不需要或者換成其他的，這個時候可以使用其他的chm編輯器或者HHW 反編譯修改后重新編譯生成,，具體操作請大家嘗試,。 使用網(wǎng)上高手改進(jìn)的版本jd2chm_0.34轉(zhuǎn)換成chm
網(wǎng)上一個高手修改了一些很多有用的地方，如果想了解的話,，請移步http://download.csdn.net/source/1024968查看并下載,。 生成英文版本如下
請注意最后一個一定要選擇y，意思就是在原Javadoc文檔里修改一點東西（就我看,，就是加了一個about.html）,，是否同意？不同意如何生成,？
生成中文版本如下
比原版本的好處是不需在放到Javadoc目錄下了,，還可以使用最新的微軟雅黑字體，而且能夠生成hhc,、hhk,、hhp文件，方便我們使用HHW進(jìn)行編輯,。遺憾還是about并且有點破壞了原Javadoc文檔（加了一個about.html）,，這個時候通過HHW工具很方便的進(jìn)行編輯（有了hhc、hhk,、hhp文件）,。修改一份給大家看看，打開hhp文件,，并打開About…文件,，修改部分內(nèi)容（就是一個html語言寫的網(wǎng)頁了） 修改完成后，保存并編譯
對比下面修改后的About
第二種：使用javadoc2chm來生成chm幫助文檔
先下載工具javadoc2chm-1.1.0.7.msi,，搜索下載（后面會提供）,，下載完成并安裝，會在開始菜單里生成程序快捷方式,。 生成英文版本如下
生成中文版本如下
界面操作,，很方便，英文支持非常好,，中文有一處亂碼（上面目錄第一層）,，幾乎很完美，遺憾是Title后面加了-Generated by javadoc2chm和中文有點亂碼，沒有生成hhc,、hhk,、hhp文件(實際上在轉(zhuǎn)換的時候是生成的這三個文件，后面被刪除了,，如果耍點小聰明的話,，可以在生成過程中復(fù)制一份，如果速度快的話,，會提示文件已經(jīng)被刪除,，是否重試，這個時候再轉(zhuǎn)換,，看文件生成后點重試即可得到這三個文件,，不要反編譯多好)，這種方法建議使用英文版本,。 自己修改了一份中文版本的轉(zhuǎn)換,，現(xiàn)提供部分步驟
看看修改后的效果吧 第一次打開的首頁
個性化設(shè)置：加入Blog，請大家有空多踩踩我的博客：http://blog.sina.com.cn/usc3l
上面的兩種方法也是我極力推薦大家使用的,，下面的兩種方法僅供學(xué)習(xí)，里面有很多問題,，中文亂碼什么的,，都會出現(xiàn)。 第三種：使用javadoc2help來生成chm幫助文檔
官方網(wǎng)站http://javadoc2help./,，下載解壓即可,，里面最重要的就是lib目錄下面的Javadoc2Help.jar，注意我們就是使用這個jar文件進(jìn)行生成,。官網(wǎng)上也提供了如何使用,。 生成英文版本如下
Cmd命令進(jìn)入jar文件目錄，寫下面的命令回車 java -jar Javadoc2Help.jar -chm -src f:\docs\api_en_US -dest f:\docs\api_en_US2 （具體路徑請根據(jù)需要修改）
注意：-dest后面的目錄請不要寫原目錄,，不然生成不了chm并且覆蓋了原目錄文件,。
生成中文版本如下
Cmd命令進(jìn)入jar文件目錄，寫下面的命令回車 java -jar Javadoc2Help.jar -chm -src f:\docs\api_zh_CN -dest f:\docs\api_zh_CN2 （具體路徑請根據(jù)需要修改）
注意：-dest后面的目錄請不要寫原目錄,，不然生成不了chm并且覆蓋了原目錄文件,。
基本能夠完成轉(zhuǎn)換，但是不了建立索引,，不能設(shè)置Title和文件名,，對中文嚴(yán)重不支持不管是英文版本還是中文版本的chm都出現(xiàn)了中文亂碼現(xiàn)象，還有chm文件就是便于查詢,，竟然不能生產(chǎn)索引,，建議不使用。 第四種：使用google code里面的javadoc2chm項目構(gòu)建
請參考http://code.google.com/p/javadoc2chm/下載ruby和javadoc2chm-0.1.zip等必要步驟。 Google code上頁介紹了如何使用,，解壓壓縮包,。使用這個，就必須先安裝ruby和HHW,。 生成英文版本如下
Cmd命令進(jìn)入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默認(rèn)安裝路徑，如果不是請自行修改）
生成的chm文件在解壓的包的文件夾里：
打開后是上面的這樣子,，具體的原因不清楚,，不過解決的方法就是把Javadoc文件夾和ruby命令的文件夾不要放在同一個盤內(nèi)，不在同一個盤里就會使用絕對路徑,。重修生成,，但是這種方法也并不適合，當(dāng)我們把原Javadoc文檔的文件夾刪除或者移動了,，這個時候也會出現(xiàn)上面的情況,。具體的我打開了hhp文件查看了一下，應(yīng)該是這種方法使用的是覺得路徑,，而并沒有把文件進(jìn)行包裝在生成,。（要查看下面截圖的效果，請把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目錄,，寫下面的命令 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)安裝路徑,，如果不是請自行修改）
不能設(shè)置Title和中文的Title時候亂碼，操作麻煩,，還要安裝ruby輔助軟件,。 總結(jié)
上面的一些不完美的地方，都可以使用HTML Help Workshop進(jìn)行改善,。實際上也是因為此次機遇,，讓我學(xué)習(xí)了HTML Help Workshop的操作，以后制作chm文檔就很方便了,。 上面方法通過參考網(wǎng)上的操作總結(jié)自己親自實際而成,，需要探討的請聯(lián)系QQ：506817493。 順利提高所有工具和制作成果的文件下載(不包括ruby輔助軟件,，自行下載) Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié).rar
|
|
|
