<!-- saved from url=(0034)http://www.fmddlmyy.cn/text21.html -->
<html><head><meta http-equiv="Content-Type" content="text/html; charset=GBK">
<title>使用doxygen为C/C++程序生成中文文档(上)</title>
</head>
<body bgcolor="seashell">
<center>
<!-- SiteSearch Google -->
<form method="get" action="http://www.google.cn/custom" target="_top">
<table border="0" bgcolor="#ffffff">
<tbody><tr><td nowrap="nowrap" valign="top" align="left" height="32">
<a href="http://www.google.com/">
<img src="./使用doxygen为C C++程序生成中文文档(上)_files/Logo_25wht.gif" border="0" alt="Google" align="middle"></a>
</td>
<td nowrap="nowrap">
<input type="hidden" name="domains" value="www.fmddlmyy.cn">
<label for="sbi" style="display: none">输入您的搜索字词</label>
<input type="text" name="q" size="31" maxlength="255" value="" id="sbi">
<label for="sbb" style="display: none">提交搜索表单</label>
<input type="submit" name="sa" value="搜索" id="sbb">
</td></tr>
<tr>
<td> </td>
<td nowrap="nowrap">
<table>
<tbody><tr>
<td>
<input type="radio" name="sitesearch" value="" id="ss0">
<label for="ss0" title="搜索网络"><font size="-1" color="#000000">Web</font></label></td>
<td>
<input type="radio" name="sitesearch" value="www.fmddlmyy.cn" checked="" id="ss1">
<label for="ss1" title="搜索 www.fmddlmyy.cn"><font size="-1" color="#000000">www.fmddlmyy.cn</font></label></td>
</tr>
</tbody></table>
<input type="hidden" name="client" value="pub-5058590656439096">
<input type="hidden" name="forid" value="1">
<input type="hidden" name="ie" value="GB2312">
<input type="hidden" name="oe" value="GB2312">
<input type="hidden" name="safe" value="active">
<input type="hidden" name="cof" value="GALT:#008000;GL:1;DIV:#336699;VLC:663399;AH:center;BGC:FFFFFF;LBGC:336699;ALC:0000FF;LC:0000FF;T:000000;GFNT:0000FF;GIMP:0000FF;FORID:1">
<input type="hidden" name="hl" value="zh-CN">
</td></tr></tbody></table>
</form>
<!-- SiteSearch Google -->
</center>
<h1><font size="5">使用doxygen为C/C++程序生成中文文档(上)</font></h1>
<p><font size="3">按照约定的格式注释源代码,用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处:</font></p>
<ul>
<li><font size="3">便于代码和文档保持同步。 </font></li>
<li><font size="3">可以对文档做版本管理。 </font></li>
</ul>
<p><font size="3">很多编程语言都有类似的文档工具,例如:Java有javadoc,Ruby有rdoc。对于C/C++程序,我们可以用Doxygen生成文档。本文通过为一个C++程序“谁养鱼”建立文档,介绍了怎样在Windows平台使用Doxygen。</font></p>
<p><font size="3">Doxygen比较适合制作API的接口文档,CHM是这类文档的常见格式。最新版本的Doxygen(目前是1.5.2)统一采用UTF-8作为输出文件的编码格式,但微软的CHM编译工具不支持UTF-8,这就为制作中文CHM文档带来麻烦。本文提出了解决这个问题的方法。</font></p>
<h2><font size="4">1 Doxygen简介</font></h2>
<h3><font size="3">1.1 要做什么</font></h3>
<p><font size="3">使用Doxygen生成文档,主要是两件事:</font></p>
<ol>
<li><font size="3">写一个配置文件(Doxyfile)。一般用Doxywizard生成后,再手工修改。 </font></li>
<li><font size="3">按照Doxygen的约定,将代码“文档化”。 </font></li>
</ol>
<p><font size="3">然后只要执行命令:</font></p>
<code><font size="3">doxygen Doxyfile </font></code>
<p><font size="3">就可以了。输入文件、输出目录、参数等都是在Doxyfile中配置的。</font></p>
<h3><font size="3">1.2 得到什么</font></h3>
<p><font size="3">Doxygen的输出格式主要有HTML、LATEX、RTF等: </font></p>
<ul>
<li><font size="3">Doxygen在输出HTML文档时,可以自动准备用于制作CHM的项目文件(.hhp)、目录文件(.hhc)和索引文件(.hhk)。用HTML Help Workshop中的CHM编译器(hhc.exe)编译后生成CHM文件。 </font></li>
<li><font size="3">Doxygen在输出LATEX文档的同时准备了转换到pdf格式的makefile。只要系统安装了合适的TEX工具,就可以从LATEX文档生成pdf文档。 </font></li>
<li><font size="3">Doxygen输出的RTF格式,已经针对Word作了优化,可以较好地转换到Word文档。 </font></li>
</ul>
<h3><font size="3">1.3 需要什么</font></h3>
<p><font size="3">完成本文的范例需要以下工具:</font></p>
<ol>
<li><font size="3">Doxygen的最新版本,可以从</font><a target="_top" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc"><font size="3">Doxygen的网站</font></a><font size="3">下载。 </font></li>
<li><font size="3">Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形,例如类的继承关系图、合作图,头文件包含关系图等。可以从</font><a target="_top" href="http://www.graphviz.org/Download..php"><font size="3">Graphviz的网站</font></a><font size="3">下载Graphviz的最新版本。Doxygen使用了Graphviz的布局引擎dot,所以在文档中将其称作dot。 </font></li>
<li><font size="3">为解决中文问题,需要使用Cygwin的iconv程序作编码转换。 </font></li>
<li><font size="3">为解决中文问题,需要一个命令行的查找替换工具。我选择了</font><a target="_top" href="http://baiy.cn/"><font size="3">白杨</font></a><font size="3">创作的工具fr。 </font></li>
</ol>
<p><font size="3">可以从我的主页</font><a href="http://www.fmddlmyy.cn/"><font size="3">http://www.fmddlmyy.cn</font></a><font size="3">下载这些工具:</font><a href="http://www.fmddlmyy.cn/download/doxytool/doxygen.rar"><font size="3">Doxygen 1.5.2</font></a><font size="3">、</font><a href="http://www.fmddlmyy.cn/download/doxytool/graphviz.rar"><font size="3">Graphviz 2.12</font></a><font size="3">、</font><a href="http://www.fmddlmyy.cn/download/doxytool/iconv.rar"><font size="3">iconv (GNU libiconv 1.9)</font></a><font size="3">和</font><a href="http://www.fmddlmyy.cn/download/doxytool/fr.rar"><font size="3">fr 2.1.1.120</font></a><font size="3">。</font></p>
<h2><font size="4">2 CHM格式的中文问题</font></h2>
<p><font size="3">前面说过:目前,Doxygen统一采用UTF-8作为输出文件的编码格式,但微软的CHM编译工具(hhc.exe)不支持UTF-8。如果直接用hhc.exe编译,中文不能正确显示。解决这个问题的思路很简单:</font></p>
<ul>
<li><font size="3">将Doxygen输出的html文件以及CHM的项目文件(.hhp)、目录文件(.hhc)和索引文件(.hhk)全部转换到GBK编码后,再用hhc.exe编译即可。</font> </li>
</ul>
<p><font size="3">可以用iconv对文件作编码转换。对于html文件,除了文件内容的编码转换外,还要将</font></p>
<p><code><font size="3"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></font></code></p>
<p><font size="3">中的“UTF-8”替换成“gb2312”。</font></p>
<h3><font size="3">2.1 用批处理简化操作</font></h3>
<p><font size="3">我写了一些批处理文件(.bat)用于简化处理过程,包括:</font></p>
<h4>2.1.1 clean.bat —— 清空以前输出</h4>
<p><code><font size="3">@echo off<br>echo 清空以前输出<br>if exist refman.chm del /f /q refman.chm<br>if exist output\html del /f /q output\html\*.*<br>if exist output\latex del /f /q output\latex\*.*<br>if exist output\rtf del /f /q output\rtf\*.*<br>if exist output del /f /q output\*.*<br></font></code></p>
<h4>2.1.2 build.bat —— 调用doxygen生成文档</h4>
<p><code><font size="3">@echo off<br>echo 生成文档<br>doxygen Doxyfile<br></font></code></p>
<h4>2.1.3 utf82gbk.bat —— 将指定文件(支持通配符)从utf-8编码转换到gbk编码</h4>
<p><code><font size="3">@echo off<br>echo 将%1从utf-8编码转换到gbk编码<br>for %%f in (%1) do copy %%f %%f.utf8<br>for %%f in (%1) do iconv -c -f utf-8 -t gbk %%f.utf8 > %%f<br></font></code></p>
<p><font size="3">这个批处理文件要求系统当前路径上有iconv.exe。执行iconv时,使用-c参数忽略无法转换的字符。否则如果输入文件包含无法转换的字符,转换会失败。输入文件被备份到加过.utf8后缀的文件。</font></p>
<h4>2.1.4 html-utf82gbk.bat —— 将指定html文件(支持通配符)从utf-8编码转换到gbk编码</h4>
<p><code><font size="3">@echo off<br>call utf82gbk %1<br>echo 将%1中的charset从UTF-8改为gb2312<br>fr %1 -f:charset=UTF-8 -t:charset=gb2312<br></font></code></p>
<p><font size="3">这个批处理文件要求系统当前路径上有iconv.exe和</font><a target="_top" href="http://baiy.cn/"><font size="3">白杨</font></a><font size="3">的fr.exe。</font></p>
<h4>2.1.5 makechm.bat —— 用Doxygen的输出制作chm文件</h4>
<p><code><font size="3">@echo off<br>echo 将Doxygen输出文件编码从utf-8转换到gbk<br>set path=%path%;%cd%<br>cd output\html<br><br>echo 处理chm输入文件<br>call utf82gbk.bat index.hhp<br>
- 1
- 2
前往页