用户工具

站点工具


docbook_notes

DocBook 笔记

Windows 下的环境配置

安装 DocBook XSL stylesheets

http://sourceforge.net/projects/docbook/files/ 下载 docbook-xsl-ns,解压至 C:\DocBook\docbook-xsl-ns-1.76.1

docbook-xsl 和 docbook-xsl-ns 的区别在于 docbook-xsl-ns 可以处理有 namespace 的 DocBook 源文件(DocBook namespace 是 DocBook 5.0 新增的),如果用 docbook-xsl 的话,其实 XSLT processor 会先去掉 namespace 再处理,多了一个步骤,所以这里下载 docbook-xsl-ns,而不是 docbook-xsl。

安装 XSLT processor - xsltproc for Windows

http://www.zlatkovic.com/pub/libxml/ 下载 iconv, libxml2, libxslt & zlib 这 4 个包,解压至 C:\DocBook\win32

安装 XSL-FO processor - FOP

http://xmlgraphics.apache.org/fop/ 下载 fop-1.0-bin.tar.gz 解压至 C:\DocBook\FOP

让 FOP 自动识别并使用系统中已经安装的可用字体

打开 C:\DocBook\FOP\conf\fop.xconf,把如下内容添加到 <renderer mime=“application/pdf”> 的 <fonts> 节点中:

<directory recursive="true">C:\Windows\Fonts</directory>
<auto-detect/>

FOP 会把识别出的字体信息 cache 起来方便以后使用,cache 文件一般位于 HOME 目录的 .fop/fop-fonts.cache。

编写生成 fo 文件时用到的 XSL 文件

如果 DocBook 源文件是纯英文的,那么直接用之前下载的 docbook-xsl-ns 里包含的 XSL 文件就可以了,但是对于含有中文的 DocBook 源文件,或者我们需要对转换过程进行一些定制的话,就要在 docbook-xsl-ns XSL 的基础上做些定制了,把如下内容写入 C:\DocBook\2ndboy.xsl:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:exsl="http://exslt.org/common"
	xmlns:fo="http://www.w3.org/1999/XSL/Format"
	xmlns:ng="http://docbook.org/docbook-ng"
	xmlns:db="http://docbook.org/ns/docbook"
	exclude-result-prefixes="db ng exsl"
	version='1.0'>
 
	<xsl:import href="file:///C:/DocBook/docbook-xsl-ns-1.76.1/fo/docbook.xsl"/>
 
	<xsl:param name="body.font.family">SimSun</xsl:param>
	<xsl:param name="body.font.size">12</xsl:param>
	<xsl:param name="monospace.font.family">Consolas</xsl:param>
	<xsl:param name="title.font.family">SimHei</xsl:param>
	<xsl:param name="page.margin.inner">2cm</xsl:param>
	<xsl:param name="page.margin.outer">2cm</xsl:param>
	<xsl:param name="hyphenate">true</xsl:param>
	<xsl:param name="paper.type" select="'A4'"/>
	<xsl:param name="draft.mode" select="'no'"/>
	<xsl:param name="fop1.extensions" select="1"/>
</xsl:stylesheet>

注意 import 的 href 路径一定要正确!

生成 PDF

Step 1: DocBook XML 转 fo

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 -o test.fo 2ndboy.xsl test.xml

Step 2: fo 转 PDF

cd C:\DocBook
FOP\fop -c FOP\conf\fop.xconf -fo test.fo -pdf test.pdf

或者一步搞定

cd C:\DocBook
FOP\fop -c FOP\conf\fop.xconf -xsl 2ndboy.xsl -xml test.xml -pdf test.pdf

生成 RTF

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 -o test.fo 2ndboy.xsl test.xml
FOP\fop -c FOP\conf\fop.xconf -fo test.fo -rtf test.rtf

生成 PNG

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 -o test.fo 2ndboy.xsl test.xml
FOP\fop -c FOP\conf\fop.xconf -fo test.fo -png test.png

生成 HTML

生成单页 HTML

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 -o test.html docbook-xsl-ns-1.76.1\html\docbook.xsl test.xml

上面这种方法生成的 HTML 里 charset 用的是 ISO-8859-1,所以汉字都变成了 &#65288;,为了让转出的 HTML 能用 UTF-8 编码,需要重载 XSL:

<?xml version='1.0' encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:exsl="http://exslt.org/common"
	xmlns:fo="http://www.w3.org/1999/XSL/Format"
	xmlns:ng="http://docbook.org/docbook-ng"
	xmlns:db="http://docbook.org/ns/docbook"
	exclude-result-prefixes="db ng exsl"
	version='1.0'>
 
	<xsl:import href="file:///C:/DocBook/docbook-xsl-ns-1.76.1/html/docbook.xsl"/>
 
	<xsl:output method="html" encoding="UTF-8" indent="no"/>
</xsl:stylesheet>

把这个文件另存为 C:\DocBook\html.xsl,用如下命令行来转换 HTML:

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 --nonet -o test.html html.xsl test.xml

生成 chunk HTML

<?xml version='1.0' encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:exsl="http://exslt.org/common"
	xmlns:fo="http://www.w3.org/1999/XSL/Format"
	xmlns:ng="http://docbook.org/docbook-ng"
	xmlns:db="http://docbook.org/ns/docbook"
	exclude-result-prefixes="db ng exsl"
	version='1.0'>
 
	<xsl:import href="file:///C:/DocBook/docbook-xsl-ns-1.76.1/html/chunk.xsl"/>
 
	<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
</xsl:stylesheet>

上面内容另存为 chunkhtml.xsl,用如下命令生成 chunk HTML:

cd C:\DocBook
win32\bin\xsltproc --encoding utf-8 --nonet -o test.html chunkhtml.xsl test.xml

示例 DocBook XML 文件

<?xml version='1.0' encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN"
	xmlns:xlink='http://www.w3.org/1999/xlink'>
	<articleinfo>
		<title>大标题</title>
		<author>
			<firstname></firstname>
			<surname></surname>
		</author>
	</articleinfo> 
	<section>
		<title>标题</title>
		<para>
			这是我的第一篇Docbook 5.0文档,欢迎你来到<link xlink:href='http://wiki.2ndboy.net/'>2ndboy 的 Wiki</link></para>
	</section>
</article>

如何让 FOP 识别自定义字体

拿宋体和黑体来举例。

提取字体信息

cd C:\DocBook\FOP
mkdir fonts
java -cp build\fop.jar;lib\avalon-framework-4.2.0.jar;lib\commons-logging-1.0.4.jar;lib\commons-io-1.3.1.jar;lib\xmlgraphics-commons-1.4.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimSun C:\Windows\fonts\simsun.ttc fonts\simsun.xml
java -cp build\fop.jar;lib\avalon-framework-4.2.0.jar;lib\commons-logging-1.0.4.jar;lib\commons-io-1.3.1.jar;lib\xmlgraphics-commons-1.4.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimHei C:\Windows\fonts\simhei.ttf fonts\simhei.xml

打开 E:\DocBook\FOP\conf\fop.xconf,把如下内容添加到 <renderer mime=“application/pdf”> 的 <fonts> 节点中:

<font metrics-url="file:///C:/DocBook/FOP/fonts/simsun.xml" kerning="yes" embed-url="file:///C:/Windows/fonts/simsun.ttc">
	<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-url="file:///C:/DocBook/FOP/fonts/simhei.xml" kerning="yes" embed-url="file:///C:/Windows/fonts/simhei.ttf">
	<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>

参考资料

docbook_notes.txt · 最后更改: 2012/10/09 06:56 由 2ndboy