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，随后将描述其使用方法。
下载转换工具时请注意对照版本号，笔者在使用中发现有些版本有bug。
-
pdf中插入图片时需用到JAVA ADVANCED IMAGING PLUG-INS, VERSION 1.0中的jar包。
-
转换中文文档需要用到字体文件simsun.ttc和simhei.ttf，中文操作系统在%system%/fonts/ 下能找到
建立目录如下(引用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的正确性。
xsltproc有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