2010年曾經(jīng)使用Doxygen生成全中文的chm文檔。由于Doxygen生成的chm目錄文件（index.hhc）本身是使用UTF-8編碼的，而古老的chm編譯器（HTML Help Workshop）對于CHM控制文件（index.hhc、index.hhk、index.hhp），卻只支持ANSI編碼（即本地編碼，如中文系統(tǒng)為GBK），所以最終編譯出來的chm文件，左邊的目錄導(dǎo)航欄全是亂碼。為了解決這個問題，可費(fèi)了一番工夫，得先使用編碼轉(zhuǎn)換工具轉(zhuǎn)換后再用chm編譯器編譯（見：使用doxygen為C/C++程序生成中文文檔）。
今天重新拿起Doxygen，驚喜地發(fā)現(xiàn)，它已經(jīng)支持生成ANSI編碼的chm目錄文件（index.hhc）了，所以能省好多工夫，現(xiàn)在終于可以一步搞定。現(xiàn)在想來，Doxygen早就應(yīng)該支持這個功能的，做起來也很簡單——當(dāng)然我沒有詳細(xì)去翻查Doxygen是從哪個版本開始支持的，反正Doxygen 1.8.0是支持的，想必之后的版本都支持。
下載和安裝 Doxygen
到 Doxygen 官網(wǎng) 下載最新的Doxygen安裝程序，然后安裝。這個軟件包包括了一個GUI界面的前端工具，可以幫助我們方便創(chuàng)建Doxygen配置文件和生成目標(biāo)文檔。
下面以 Doxygen 1.8.0 為例進(jìn)行講解。
下載和安裝 chm 編譯器
我們使用微軟古老的 HTML Help Workshop 1.3，這個軟件N久沒更新了。
下載地址： 微軟官網(wǎng)
下載后根據(jù)提示安裝。
項目一般設(shè)置
首先在“Wizard”標(biāo)簽的Project項進(jìn)行如下設(shè)置：
-
項目名稱：將在最新的文檔首頁中顯示
-
源碼列表：選擇要生成文檔的源代碼或目錄，可以有多個文件或目錄形成一個列表。建議使用相對路徑，相對于當(dāng)前目錄（也即當(dāng)前配置文件所在的目錄）
-
遞歸掃描：如果需要對整個源碼目錄下的所有子目錄及文件生成文檔，請勾選本項
-
輸出目錄：設(shè)置最終生成的幫助文檔的存儲路徑，建議使用相對路徑
下一步，Mode項，根據(jù)需要設(shè)置文檔生成模式。
下一步，Output項，設(shè)置輸出格式，勾選HTML和“prepare for compressed HTML(.chm)”
然后切換到“Expert”標(biāo)簽的“HTML”項，設(shè)置HTML和CHM相關(guān)的選項：
-
GENERATE_HTMLHELP：確保已經(jīng)勾選了
-
CHM_FILE：最終生成的.chm的文件名，如“HkcProjectHelp.chm”。默認(rèn)為“index.chm”。可以使用路徑，也可以使用相對路徑，相對于上面設(shè)置的輸出目錄的html目錄（建設(shè)使用上一級目錄，如“..\MyDoc.chm”）
-
HHC_LOCATION：chm 編譯器（hhc.exe）的全路徑。請指到
HTML Help Workshop 的安裝目錄的 hhc.exe 程序
-
CHM_INDEX_ENCODING：chm索引文件編碼，下面會講到，這里填“GBK”
編碼設(shè)置
編碼設(shè)置很重要，如果設(shè)置不當(dāng)，生成的文檔會出現(xiàn)亂碼。因為 Doxygen 汲及的東西多，有好幾項編碼設(shè)置，所以需要認(rèn)真對待，根據(jù)項目的實情情況設(shè)置。
所有高級設(shè)置（包括編碼設(shè)置）都在“Expert”標(biāo)簽，重要的設(shè)置項如下：
-
Project/DOXYFILE_ENCODING：當(dāng)前 Doxygen 配置文件本身的字符編碼，默認(rèn)為UTF-8，一般不需要修改
-
Project/OUTPUT_LANGUAGE：輸出語言。這里是指Doxygen自己生成的導(dǎo)航、提示、幫助等文本的文字采用的語言。我們希望幫助文檔是全中文的，所以選擇Chinese
-
Input/INPUT_ENCODING：輸入文件的編碼。這里是指我們的源代碼文件本身的編碼。在Windows平臺一般是系統(tǒng)編碼（GBK），而Linux平臺一般是UTF-8。請用文本編輯器查看源文件的編碼。這里如果設(shè)置的不一致，源碼文件的注釋中所有非ASCII字符將在生成的文檔中變成亂碼。
-
HTMP/CHM_INDEX_ENCODING：這里設(shè)置Doxygen生成的CHM索引文件的編碼，以前是不能設(shè)置的，默認(rèn)為UTF-8，而微軟的編譯器不能識別UTF-8編碼的索引文件，所以最終造成左邊目錄導(dǎo)航欄亂碼。我們設(shè)置它為GBK，這樣Doxygen將為我們生成GBK編碼的索引文件（.hhc、.hhk、.hhp）
生成CHM文檔
設(shè)置好了后，點擊“Run”→“Run doxygen”生成最終的.chm文檔，如果設(shè)置正確，打開后是全中文的了。