版本0.1
版权 © 2005 lt
本文档采用docBook-xml-4.2标准书写,使用saxon6.5.3输出html和fo,用fop0.20.5把fo转换成pdf。
刚开始用docbook写文档觉得非常的不适应，毕竟比起用所见即所得的编辑工具来，要费事很多，其中文档的转换我就很费周折， 最终通过查阅网上资料得以解决，希望本文能给正在为转换docbook文档而困扰的人以帮助。
开始本文之前给出网上两篇文章的链接：limodou写的<<docbook学习>>, 是我学习docbook入门的文章；曹晓纲写的<<Add Asia fonts to docbook-fop , Hibernate style>>指导我转换docbook文档。
目录
概述 1. saxon-fop 1.1. 下载工具 1.2. 搭建环境 2. xsltproc 概述虽然在刚开始写docbook文档的时候会有些不适，但是当看到规范清晰的文档时，我相信此刻会填补你 所有的不满与牢骚。动手写过几篇文章后就会习惯docbook的语法规则，其实docbook常用的元素也不是 很多。
docbook文档有sgml、xml、两种格式，转换文档样式也有相对应的两种格式dsssl、xsl 本人用的是遵循docbook-xml-dtd规则的xml文档格式。sgml也是一种标识语言，早于 xml.
通过转换工具解析docbook文档和转换样式，就可以生成规范、多样的文档。如html形式，pdf、rtf、chm javadoc等格式。 本人使用过的转换工具xsltproc、saxon、fop，随后将描述其使用方法。
第 1 章 saxon-fop 1.1. 下载工具下载转换工具时请注意对照版本号，笔者在使用中发现有些版本有bug。
docbook-dtd-4.2
docbook-xsl-1.65.1
saxon6.5.3
fop0.20.5
pdf中插入图片时需用到JAVA ADVANCED IMAGING PLUG-INS, VERSION 1.0中的jar包。
转换中文文档需要用到字体文件simsun.ttc和simhei.ttf，中文操作系统在%system%\fonts\ 下能找到
1.2. 搭建环境建立目录如下(引用hibernate中文手册目录结构)： |---docbook +---suport +---lib (1) +---docbook-dtd +---docbook-xsl +---zh-cn (2) +---images +---styles +---fop +---modules |---master.xml |---build.xml (3)
(1)放置转换工具组件。
(2)将文档所用的图片放置到images,转换样式及css放置styles文件夹中，fop文件中放置转换fop的所需 的字体文件。待转换的docbook源文件放置在modules文件夹中，master.xml文件为docbook文档的起始文件。
(3)ant的构建文件。
1、将下载工具中*.jar文件拷贝到lib
2、利用fop0.20.5生成中文pdf文件时，请做以下操作(摘自曹晓纲“docbook + TTF + FOP 编写中文”)
fop默认没有支持中文字体。解决办法是从windows的TTF字体中提取fontmatrix文件. java-cpD:\works\hibernate2\doc\reference\support\lib\fop.jar;D:\works\hibernate2\doc\ reference\support\lib\avalon-framework-cvs-20020806.jar org.apache.fop.fonts.apps.TTFReader C:\Windows\Fonts\simhei.ttf simhei.xml java -cp D:\works\hibernate2\doc\reference\support\lib\fop.jar;D:\works\hibernate2\doc\reference \support\lib\avalon-framework-cvs-20020806.jar org.apache.fop.fonts.apps.TTFReader -ttcname "SimSun" C:\Windows\Fonts\simsun.ttc simsun.xml 得到两个xml文件：simsun.xml, sumhei.xml;然后在userconfig.xml中注册： <fonts> <font metrics-file="simhei.xml" embed-file="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="simsun.xml" embed-file="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> </fonts> ok,字体的问题即可解决
生成的pdf文件的中文每一行都很长，没有断开。在limodou的blog中曾经提到，如果把docbook的zh-cn强制改为zh, 并且做两个假的zh.xml文件即可解决这个问题。显然这是fop的一个bug.fop源代码： org.apache.fop.layout.LineArea.java 第1407行： String lang = hyphProps.language.toLowerCase(); if ("zh".equals(lang) || "ja".equals(lang) || "ko".equals(lang) || "vi".equals(lang)) ret = true; 显然问题就出在这里。作者想当然的编写了一些需要断字的case,却没有遵守RFC 3066规范。 修改为： if (lang.startsWith("zh" || lang.startsWith("ja" || lang.startsWith("ko" || lang.startsWith("vi") ret = true; 重新编译fop. 搞定。
3、建立ant的构建文件。
ant是一个非常好用的构建工具，使用和配置都很简单，这里不再对ant进行描述。本文引用hibernate汉化 工作组的build.xml文档
例 1.1. build.xml
<project name="HibernateDocumentation" default="all.doc" basedir="."> <!-- Set build directories for all formats. --> <property name="build.dir" value="${basedir}/build"/> <!-- Support files for build process. --> <property name="support.dir" value="${basedir}/support"/> <!-- Set DocBook stylesheets. --> <property name="db.style.fopdf" value="fopdf.xsl"/> <property name="db.style.html" value="html_chunk.xsl"/> <property name="db.style.htmlsingle" value="html.xsl"/> <!-- Classpath for the build tools. --> <path id="lib.classpath"> <fileset dir="${support.dir}/lib"> <include name="**/*.jar"/> </fileset> </path> <!-- ################################################################## --> <target name="all.doc" depends="clean" description="Compile documentation for all languages and all formats."> <!-- TRANSLATOR: Duplicate this line for your language --> <!--<antcall target="lang.all"><param name="lang" value="en"/></antcall>--> <antcall target="lang.all"><param name="lang" value="zh-cn"/></antcall> </target> <target name="all.revdiff" description="Generates a diff report for all translated versions."> <!-- TRANSLATOR: Duplicate this line for your language --> <antcall target="lang.revdiff"><param name="lang" value="de"/></antcall> </target> <!-- ################################################################## --> <target name="clean"> <!-- Delete build directory. --> <delete dir="${build.dir}"/> </target> <target name="lang.all"> <!-- Compile the documentation for a single language in all formats. --> <antcall target="lang.docpdf"/> <antcall target="lang.dochtml"/> <antcall target="lang.dochtmlsingle"/> <antcall target="lang.htmlmisc"/> </target> <target name="lang.docpdf.prepare"> <!-- Copy all the images to the output location, will be removed later. --> <copy todir="${build.dir}/${lang}/pdf/images"> <fileset dir="${basedir}/${lang}/images"> <include name="**/*.png"/> <include name="**/*.svg"/> <include name="**/*.gif"/> </fileset> </copy> <!-- Create the XSL/FO temporary file. --> <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${basedir}"> <classpath refid="lib.classpath"/> <arg value="-o"/> <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/> <arg value="${basedir}/${lang}/master.xml"/> <arg value="${basedir}/${lang}/styles/${db.style.fopdf}"/> </java> <available property="custom.fop.userconfig.present" file="userconfig.xml" filepath="${basedir}/${lang}/fop"/> </target> <target name="lang.docpdf.customized" depends="lang.docpdf.prepare" if="custom.fop.userconfig.present"> <copy todir="${build.dir}/${lang}/pdf"> <fileset dir="${basedir}/${lang}/fop"> <include name="*"/> </fileset> </copy> <!-- Create a PDF from the XSL/FO, using customized fop userconfig.xml --> <java classname="org.apache.fop.apps.Fop" fork="true" dir="${basedir}"> <classpath refid="lib.classpath"/> <arg value="-c"/> <arg value="${basedir}/${lang}/fop/userconfig.xml"/> <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/> <arg value="${build.dir}/${lang}/pdf/hibernate_reference.pdf"/> </java> </target> <target name="lang.docpdf.normal" depends="lang.docpdf.prepare" unless="custom.fop.userconfig.present"> <!-- Create a PDF from the XSL/FO. --> <java classname="org.apache.fop.apps.Fop" fork="true" dir="${basedir}"> <classpath refid="lib.classpath"/> <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/> <arg value="${build.dir}/${lang}/pdf/hibernate_reference.pdf"/> </java> </target> <!--<target name="lang.docpdf" depends="lang.docpdf.normal,lang.docpdf.customfop">--> <target name="lang.docpdf" depends="lang.docpdf.normal,lang.docpdf.customized"> <!-- House keeping,delete temporary files. --> <!-- <delete file="${build.dir}/${lang}/pdf/docbook_fop.txt"/> <delete dir="${build.dir}/${lang}/pdf/images"/> <delete> <fileset dir="${build.dir}/${lang}/pdf" includes="**/*.xml"/> </delete> --> </target> <target name="lang.dochtml"> <mkdir dir="${build.dir}/${lang}/html/"/> <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${build.dir}/${lang}/html"> <classpath refid="lib.classpath"/> <arg value="${basedir}/${lang}/master.xml"/> <arg value="${basedir}/${lang}/styles/${db.style.html}"/> </java> </target> <target name="lang.dochtmlsingle"> <mkdir dir="${build.dir}/${lang}/html_single/"/> <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${basedir}"> <classpath refid="lib.classpath"/> <arg value="-o"/> <arg value="${build.dir}/${lang}/html_single/index.html"/> <arg value="${basedir}/${lang}/master.xml"/> <arg value="${basedir}/${lang}/styles/${db.style.htmlsingle}"/> </java> </target> <target name="lang.htmlmisc"> <!-- Copy images and CSS for HTML documentation, language specific. --> <copy todir="${build.dir}/${lang}/shared/images"> <fileset dir="${basedir}/${lang}/images"> <include name="**/*.png"/> <include name="**/*.gif"/> </fileset> </copy> <copy todir="${build.dir}/${lang}/shared/css"> <fileset dir="${basedir}/${lang}/styles"> <include name="**/*.css"/> </fileset> </copy> </target> <target name="lang.revdiff"> <taskdef name="revdiff" classname="org.hibernate.docproc.revdiff.RevDiffReportTask" classpathref="lib.classpath"> </taskdef> <revdiff original="${basedir}/en/master.xml" copy="${basedir}/${lang}/master.xml" report="${build.dir}/status_${lang}.html"/> </target> </project>
通过上述配置之后，进入该目录运行ant,转换的文档将会放置build目录下，在转换之前请验证xml的正确性。
第 2 章 xsltprocxsltproc有c和java两种语言的版本。本文描述的是c语言版本的。下载xlstproc。
1、建立如下目录
|---docbook +---bin (1) +---lib (2) +---source +---docbook-dtd +---docbook-xsl (1) 将xsltproc中*.exe文件放置该文件夹下。 (2) 将xsltproc中所有lib下的文件放置该文件夹下。
2、将bin和lib实际路径设置到系统环境path路径。
以下是xsltproc常用的转换命令
--生成rtf文件 xsltproc 转换样式文件.xsl 待转换文件.xml > 输出文件.rtf 例：xsltproc C:\share\style\docbook-xsl-1.65.1\html\docbook.xsl c:\share\demo1.xml > c:\share\demo3.rtf --生成html文件（分页文件） xsltproc -o 输出目录 转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:\share\src\ C:\share\style\docbook-xsl-1.65.1\html\chunk.xsl c:\share\demo1.xml --生成html文件（单页文件） xsltproc -o 输出文件.html 转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:\share\src\demo11.html C:\share\style\docbook-xsl-1.65.1\html\docbook.xsl c:\share \demo1.xml --生成htmlHelp文件 xsltproc -o 输出目录 转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:\share\src\ C:\share\style\docbook-xsl-1.65.1\htmlhelp\htmlhelp.xsl c:\share\demo1.xml --生成javaHelp文件 xsltproc -o 输出目录 转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:\share\src\ C:\share\style\docbook-xsl-1.65.1\javahelp\javahelp.xsl c:\share\demo1.xml --生成xml文件 xsltproc -o 输出文件.xml 转换样式文件.xsl 待转换文件.xml 例: xsltproc -o c:\share\src\demo1_xml.xml C:\share\style\docbook-xsl-1.65.1\Xhtml\docbook.xsl c:\share \demo1.xml --生成fo文件 xsltproc xsltproc 转换样式文件.xsl 待转换文件.xml > 输出文件.fo xsltproc C:\share\style\docbook-xsl-1.65.1\fo\fop.xsl c:\share\demo1.xml > c:\share\my.fo
本文地址：http://com.8s8s.com/it/it23487.htm