Rain's Blog

Docbook提供了大量的XML标记，以一种表现层中立的方式，使作者只关注文档结构和内容，从而可以借助一些免费工具来创建多种文件格式，如HTML、PDF以及更多其他。更重要的是XML文件的工具非常多，处理起来也非常方便。但是对于中文的支持方面，就不是很好，本人在安装使用时就遇到了麻烦。后来google了一下，发现很多人都遇到过类似的问题，也都给出了自己的解决办法，我也参考了很多。但是有些地方描述的不是很清楚，使得安装Docbook并不轻松，本文也算是补充一下，写出我的一些安装和使用心得，希望对有需要的朋友有所帮助。 1 下载 1) 下载Docbook DTD 下载网址http://www.oasis-open.org/docbook/xml/，你可以选择合适的版本，这里我下载的是4.5，详细链接http://www.oasis-open.org/docbook/xml/4.5/docbook-xml-4.5.zip 2) 下载Docbook XSL Docbook XSL的网站http://docbook.sourceforge.net/，当前最新稳定版本是1.72.0。 3) 下载saxon Saxon网站：http://saxon.sourceforge.net/，选择6.5.5版本，详细链接http://prdownloads.sourceforge.net/saxon/saxon6_5_5.zip。 4) 下载libxml 下载地址http://www.zlatkovic.com/pub/libxml/，xsltproc和saxon，你可以选择其中一种来生成html文件和fo文件。xsltproc是用c开发的，效率较高。还有一种选择是安装cygwin，里面包含该工具集。 5) 下载fop Fop是apache的一个项目，用来转换fo文件至pdf文件。目前最新版本是0.93，但这里仍然使用0.20.5，后面需要解决掉其中一个bug，因此源码也需要一并下载。官方网站：http://xmlgraphics.apache.org/fop 6) 下载Java SE 选择1.5.x版本下载，http://java.sun.com/javase/downloads/index.jsp。补充：我第二次安装的时候，发现1.5版本不能创建后面的字体。 7) 下载Ant 做Java开发没有不知道的build工具，即使你不了解，安装起来也非常简单，就不多说了。 在上面的软件下载好后，存放在一起，准备好后，开始下面的安装。 2 安装 在安装之前，先建立安装目录，例如C:\Docbook，创建tools目录，这里将会存放工具，以便后面使用。

C:\Docbook
      |
    |----docbook     // 这里是docbook项目，包含你要撰写的文章的src，build file，在本文附件处提供了下载。
           |----conf
           |----lib  // 存放saxon以及其他的jar
       |----src
       |----build.bat, build.xml   // ant所需的build文件
    |----tools
           |
       |----bin  // 存放xsltproc
       |----dtd  // 存放docbook dtd
       |----xsl  // 存放docbook xsl


1) Docbook DTD 解压docbook-xml-4.5.zip至C:\Docbook\tools\dtd。 2) Docbook XSL 解压docbook5-xsl-1.72.0.zip至C:\Docbook\tools，更名文件夹为xsl。 3) Saxon 解压saxon6-5-5.zip，将saxon.jar，saxon-jdom.jar，saxon-xml-apis.jar复制到lib目录。 4) libxml 全部解压后，将bin中的文件全部复制到上面的tools\bin目录中。此外还需要设置环境变量PATH=%PATH%;C:\Docbook\tools\bin。感动很奇怪的是，必须这样做，我用ant认为exec时，是可以找到xsltproc的，但是却无法运行，返回错误码为2，也就是找不到文件，但是实际上看运行日志是找到的了。不解？ 5) fop 解压安装至C:\fop-0.20.5，这里你也可以是其他位置，只需要设置环境变量FOP_HOME，或者编辑build.bat。 6) jdk 安装很简单，就不说了。需设置环境变量JAVA_HOME。 7) ant 解压到某个目录，需设置环境变量ANT_HOME。 这样依次按照上面的步骤，安装已经完成。你可以测试一下工具是否安装成功，以便进行后续的设置。 3 设置 这里的设置主要是针对fop对中文的处理，需要解决fop的一个bug和创建中文字体配置文件，还是有点麻烦的，我就花费了三天的时间来解决这个问题，这也是最关键的地方。 1) 首先得自己修改fop的源代码，解决掉其中一个bug，就是不支持zh_cn语言。用编辑器打开fop-0.20.5\src\org\apache\fop\layout\LineArea.java文件，在1407行找到下面的代码片断。

            if ("zh".equals(lang) || "ja".equals(lang) || "ko".equals(lang)
                || "vi".equals(lang))
                ret = true;


修改如下：

            if (lang == null) {
              return false;
            }
            if (lang.startsWith("zh") || lang.startsWith("ja") || lang.startsWith("ko") 
                || lang.startsWith("vi")) {
                ret = true;
            }


双击fop-0.20.5-src\fop-0.20.5\build.bat，将生成的build\fop.jar，替换掉fop安装目录build下的文件。 2) 接着我们需要创建几种字体文件。首先进入fop安装目录，复制fop.bat文件更名为ttfreader.bat。然后用记事本打开，修改其内容如下：

@ECHO OFF

rem %~dp0 is the expanded pathname of the current script under NT
set LOCAL_FOP_HOME=
if "%OS%"=="Windows_NT" set LOCAL_FOP_HOME=%~dp0

set LIBDIR=%LOCAL_FOP_HOME%lib
set LOCALCLASSPATH=%LOCAL_FOP_HOME%build\fop.jar
set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\xml-apis.jar
set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\xercesImpl-2.2.1.jar

java -cp "%LOCALCLASSPATH%" org.apache.fop.fonts.apps.TTFReader %1 %2 %3 %4 %5 %6 %7 %8 


这里之所以要删掉xalan-2.4.1.jar，是因为该版本有问题。 在C:\Windows\fonts下找到simsun.ttc、simhei.ttf、cour.ttf，复制其至fop安装目录下。最后在CMD，依次使用下面的命令来生成相应的字体描述文件。

ttfreader -ttcname "SimSun" simsun.ttc simsun.xml
ttfreader -ttcname "SimHei" simhei.ttf simsun.xml
ttfreader -ttcname "Courier New" cour.ttf courier.xml


如果不出错的话，将会生成simsun.xml、simhei.xml和courier.xml。将他们拷贝到fop安装目录下的fonts中。

mkdir fonts
move simsun.xml fonts\simsun.xml
move simhei.xml fonts\simhei.xml
move courier.xml fonts\courier.xml


3) 设置fop，编辑conf\userconfig.xml，修改其内容如下所示： <configuration>   <entry>     <key>fontBaseDir</key>     <value>C:\fop-0.20.5</value>   </entry>   <fonts>   <font metrics-file="fonts/simsun.xml" embed-file="c:\windows\fonts\simsun.ttc" kerning="yes">       <font-triplet name="SimSun" style="normal" weight="normal"/>     <font-triplet name="SimSun" style="normal" weight="bold"/>     <font-triplet name="SimSun" style="italic" weight="normal"/>     <font-triplet name="SimSun" style="italic" weight="bold"/>   </font>   <font metrics-file="fonts/simhei.xml" embed-file="c:\windows\fonts\simhei.ttf" kerning="yes">     <font-triplet name="SimHei" style="normal" weight="normal"/>     <font-triplet name="SimHei" style="normal" weight="bold"/>     <font-triplet name="SimHei" style="italic" weight="normal"/>     <font-triplet name="SimHei" style="italic" weight="bold"/>   </font>   <font metrics-file="fonts/courier.xml" embed-file="c:\windows\fonts\cour.ttf" kerning="yes">     <font-triplet name="CourierNew" style="normal" weight="normal"/>     <font-triplet name="CourierNew" style="normal" weight="bold"/>     <font-triplet name="CourierNew" style="italic" weight="normal"/>     <font-triplet name="CourierNew" style="italic" weight="bold"/>   </font>   </fonts> </configuration> 按照上面的步骤完成后，fop的改造工作也就完成了。下面将是介绍如何使用docbook来创建html和pdf文件。 4 使用 下载本文提供的附件docbook-1.0.zip，解压带C:\Docbook目录，注意不是C:\Docbook\docbook。 这里需要编辑build.bat文件，修改FOP_HOME，设置为实际安装目录。 下面打开CMD窗口，进入到C:\Docbook\docbook，就可以进行相关的操作了。 C:\Docbook\docbook>build Buildfile: build.xml help:      [echo]      [echo] Docbook build file      [echo] -----------------------------------      [echo]      [echo] Available targets are:      [echo]      [echo] help         --> Display usage      [echo] html         --> Using saxon to generate html files      [echo] fo           --> Using saxon to generate fo files      [echo] pdf          --> Using fop to generate pdf files      [echo] xp-html      --> Using xsltproc to generate html files      [echo] xp-fo        --> Using xsltproc to generate fo files      [echo]      [echo] new          --> Create a new docbook project      [echo] dist         --> Creates release (source) distribution      [echo]      [echo] clean        --> Clean build files BUILD SUCCESSFUL Total time: 2 seconds C:\Docbook\docbook>build new Buildfile: build.xml clean:      [echo] Cleaning build and distribution directories    [delete] Deleting directory C:\Development\docbook\docbook\target new:     [input] What would you like to name your docbook project [mydb]? [mydb] mybook      [echo] Creating new application named 'mybook'...      [copy] Copying 13 files to C:\Development\docbook\mybook      [copy] Copied 7 empty directories to 2 empty directories under C:\Docbook\mybook BUILD SUCCESSFUL Total time: 13 seconds 按照上面的命令，help命令会打印出帮助信息，html命令用来生成html文件，fo命令用来生成fo文件，pdf命令用来生成pdf文件，xp-html命令是使用xlstproc工具来创建html文件，xp-fo命令是使用xlstproc工具来创建fo文件，new命令会创建一个新docbook项目。 5 定制 在docbook\conf\xsl有html-stylesheet.xsl和fo-stylesheet.xsl两个文件，你可以修改其中一些参数，或是增加其他设置，来定制你自己的文件样式。 1) HTML的样式表设置 <!-- Automatic labelling --> <xsl:param name="section.autolabel" select="1"/> <xsl:param name="section.label.includes.component.label" select="1"/> <!-- HTML --> <xsl:param name="html.stylesheet" select="'styles.css'"/> <xsl:param name="draft.mode" select="'no'"></xsl:param> <!-- Miscellaneous --> <xsl:param name="highlight.default.language" select="'java'"/> <xsl:param name="highlight.source" select="1"/> <xsl:param name="toc.section.depth">3</xsl:param> <xsl:param name="annotate.toc">0</xsl:param> <xsl:template match="sect1" mode="toc"> <xsl:param name="toc-context" select="."/> <xsl:call-template name="subtoc">   <xsl:with-param name="toc-context" select="$toc-context"/>   <xsl:with-param name="nodes"    select="sect2|refentry|bridgehead[$bridgehead.in.toc != 0]"/> </xsl:call-template> </xsl:template> <xsl:template match="sect2" mode="toc"> <xsl:param name="toc-context" select="."/> <xsl:call-template name="subtoc">   <xsl:with-param name="toc-context" select="$toc-context"/>   <xsl:with-param name="nodes"    select="sect3|refentry|bridgehead[$bridgehead.in.toc != 0]"/> </xsl:call-template> </xsl:template> 2) FO的样式表设置 <!-- Admonitions --> <xsl:param name="admon.graphics" select="1"/> <!--Callouts --> <xsl:param name="callout.graphics" select="0"/> <xsl:param name="callout.unicode" select="1"/> <xsl:param name="callout.unicode.font" select="'SimSun'"/> <xsl:param name="callout.unicode.start.character" select="10102"></xsl:param> <!-- ToC/LoT/Index Generation --> <!-- Processor Extensions --> <xsl:param name="fop.extensions" select="1"/> <!-- Stylesheet Extensions --> <xsl:param name="tablecolumns.extension" select="0"/> <xsl:param name="use.extensions" select="1"/> <!-- Automatic labelling --> <xsl:param name="section.autolabel" select="1"/> <xsl:param name="section.label.includes.component.label" select="1"/> <!-- Miscellaneous --> <xsl:param name="variablelist.as.blocks" select="1"></xsl:param> <!-- Pagination and General Styles --> <xsl:param name="paper.type" select="'A4'"/> <xsl:param name="hyphenate">false</xsl:param> <xsl:param name="draft.mode" select="'no'"/> <!--Font Families --> <xsl:param name="body.font.family">SimSun</xsl:param> <xsl:param name="dingbat.font.family" select="'SimSun'"></xsl:param> <xsl:param name="monospace.font.family">CourierNew</xsl:param> <xsl:param name="sans.font.family" select="'sans-serif'"></xsl:param> <xsl:param name="title.font.family">SimHei</xsl:param> <xsl:param name="symbol.font.family" select="'Symbol,ZapfDingbats'"></xsl:param> <!-- Property Sets --> <!-- Localization --> <xsl:param name="l10n.gentext.default.language" select="'zh_cn'"/> <xsl:param name="l10n.gentext.language" select="'zh_cn'"/> 6 后记 本文的完成借鉴了其他网友的文章，按照我自己安装docbook的经过，整理了一下。在此对他们也表示感谢，也欢迎你在使用过程中，给与意见和建议，我会继续努力的。写完这篇文章，已经是凌晨1：40，是该睡觉了，幸好有歌作伴，昨晚熬夜看欧冠，今天的确很困了。 7 参考资料 1) http://blog.donews.com/limodou/archive/2004/04/01/9917.aspx 2) http://caoxg.blogcn.com/diary,101113758.shtml 3) http://www.cnblogs.com/ericguo/archive/2007/02/25/ fop_20_5_chinese_patch.aspx 4) http://www.parsesoft.net/DocumentFiles/ dc03e8b3-95f4-493e-9fdb-f88c70758034/index.html 8 资源 1) http://docbook.sourceforge.net/ 2) http://saxon.sourceforge.net/ 3) http://www.oasis-open.org/docbook/ 4) http://xmlgraphics.apache.org/fop/ 5) http://www.zlatkovic.com/pub/libxml/ 6) http://java.sun.com/javase/downloads/index.jsp 7) http://ant.apache.org/ 8) http://www.cygwin.com/ 9 源码 docbook-1.0.zip docbook.pdf