Transition Docbook
版本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文档。
目录
概述
虽然在刚开始写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。
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)
放置转换工具组件。
将文档所用的图片放置到images,转换样式及css放置styles文件夹中，fop文件中放置转换fop的所需 的字体文件。待转换的docbook源文件放置在modules文件夹中，master.xml文件为docbook文档的起始文件。
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\docreference\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 章 xsltproc
xsltproc有c和java两种语言的版本。本文描述的是c语言版本的。下载xlstproc。
1、建立如下目录
|---docbook
+---bin (1)
+---lib (2)
+---source
+---docbook-dtd
+---docbook-xsl
将xsltproc中*.exe文件放置该文件夹下。
将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
