mingdu.zheng <at> gmail <dot> com
1. 簡介
DocBook 本身是支援中文的,但需要一些額外的工作, 本文介紹如何為 DocBook XML 标簽添加語言屬性以支援中文辨別; 介紹如何自定義樣式表以輸出 UTF-8 編碼的 HTML 檔案; 介紹如何生成字型資訊檔案以供 Fop 使用; 介紹自定義樣式表以支援 PDF 書簽和 PDF 中文字型; 介紹如何自定義 Fop 配置檔案以支援嵌入中文字型。
本文使用 Eclipse 編輯 DocBook XML , 使用 Ant、Xalan、Fop 将 DocBook XML 轉換成 HTML 和 PDF 格式, 如果您使用其它工具需要根據您使用的工具做相應的改動,特别是 Ant 腳本相關的部分, 如果您也希望使用上述工具編輯和轉換 DocBook XML , 請參考《在 Eclipse 中建構 DocBook XML》。
本文使用 DocBook XML 編輯并轉換成 HTML 和 PDF,點選文章頭部的“下載下傳文章” 下載下傳本文的 DocBook XML 源檔案,包括 Ant 腳本、自定義樣式表、配置檔案。
2. 所需的 Eclipse 插件
編輯 DocBook XML 需要安裝Eclipse XML Editors and Tools 和 Eclipse XSL Developer Tools 這兩個插件,轉換 DocBook XML 需要安裝Eclipse Java Development Tools 插件, 不是要進行 Java 開發,而是要使用其中的 Ant 建構工具。 如果未安裝上訴插件可以通過選擇“Help > Install New Software…” 安裝插件。
3. 顯示“目錄”而不是“Contents”
DocBook 轉換過程會根據文檔結構自動産生部分内容,例如文檔目錄, 預設情況下目錄頂部顯示的是“Contents”而不是“目錄”, 為 DocBook XML 的根标簽添加 xml:lang 屬性為 “zh_cn”,讓 DocBook 産生“目錄”而不是“Contents”。
<article xml:lang="zh_cn">
4. 生成 UTF-8 編碼的 HTML
預設情況下,DocBook 官方樣式表使用“ISO-8859-1”編碼, 在這種編碼模式下中文将以 Unicode 編碼的形式儲存, 例如“中文支援”被存儲成“中文支持”的形式, 這不影響浏覽器對中文字元的解析,但是占用更多的存儲空間,生成的 HTML 代碼幾乎沒有可讀性。
通過自定義樣式表,可以将字元編碼更改為更加通用的 “UTF-8” 編碼, 建立 xsl 檔案,命名為
html.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:include href="../docbook-xsl-1.78.1/html/docbook.xsl"/>
<!-- 更改輸出選項,使用 UTF-8 編碼 -->
<xsl:output method="html" encoding="UTF-8" indent="no"/>
</xsl:stylesheet>
注意 |
根據 docbook-xsl 的存儲路徑和版本對引用路徑作适當調整 |
修改 Ant 腳本,使用自定義樣式表作為 HTML 轉換的樣式表
...
<property name="html.stylesheet" value="${src.dir}/html.xsl" />
...
5. 生成支援中文的 PDF 檔案
使用 Fop 生成 PDF 時, Fop 使用的預設字型不包含中文字元, 是以使用 Fop 生成中文 PDF 檔案需要為 Fop 指定中文字型。
5.1. 生成字型描述資訊檔案
Fop 提供了生成字型描述資訊檔案的工具 “org.apache.fop.fonts.apps.TTFReader” 編輯 Ant 腳本,添加下述内容,讓 Ant 為我們自動建立字型描述資訊檔案。
<!--
- target: build-font
- description: 生成PDF嵌入字型資訊。
-->
<target name="build-font" depends="mkdir-out"
description="Build embedded fonts information">
<!-- 生成TTF字型資訊 -->
<java fork="true" classname="org.apache.fop.fonts.apps.TTFReader">
<classpath>
<fileset dir="${fop.lib.dir}">
<include name="*.jar" />
</fileset>
<fileset dir="${fop.build.dir}">
<include name="fop.jar" />
</fileset>
</classpath>
<arg value="C:\WINDOWS\Fonts\SimHei.ttf"/> <!-- TTF字型檔案 -->
<arg value="${out.dir}/SimHei.xml"/> <!-- 字型資訊檔案 -->
</java>
<!-- 生成TTC字型集中一種字型資訊 -->
<java fork="true" classname="org.apache.fop.fonts.apps.TTFReader">
<classpath>
<fileset dir="${fop.lib.dir}">
<include name="*.jar" />
</fileset>
<fileset dir="${fop.build.dir}">
<include name="fop.jar" />
</fileset>
</classpath>
<arg value="-ttcname"/> <!-- 選擇字型集中的一種字型 -->
<arg value="SimSun"/> <!-- 選擇的字型名稱 -->
<arg value="C:\WINDOWS\Fonts\SimSun.ttc"/> <!-- 字型集,包含多種字型 -->
<arg value="${out.dir}/SimSun.xml"/> <!-- 字型資訊檔案 -->
</java>
<!-- 生成TTF字型資訊 -->
<java fork="true" classname="org.apache.fop.fonts.apps.TTFReader">
<classpath>
<fileset dir="${fop.lib.dir}">
<include name="*.jar" />
</fileset>
<fileset dir="${fop.build.dir}">
<include name="fop.jar" />
</fileset>
</classpath>
<arg value="C:\WINDOWS\Fonts\TIMES.TTF"/> <!-- TTF字型檔案 -->
<arg value="${out.dir}/TimesNewRoman.xml"/> <!-- 字型資訊檔案 -->
</java>
</target>
調用 “build-font” 目标将生成 SimHei(黑體)、SimSun(宋體)、Times New Roman 三種字型的描述, 生成的檔案分别為 SimHei.xml、SimSun.xml、TimesNewRoman.xml。
5.2. 自定義 Fop 配置檔案
将
fop-1.1/conf/fop.xconf
拷貝一份到
src
目錄,修改
src/fop.xconf
, 添加嵌入字型相關選項。
<renderer mime="application/pdf">
<filterList>
<value>flate</value>
</filterList>
<fonts>
<!-- 中文字型:黑體 -->
<font metrics-url="out/SimHei.xml" kerning="yes" embed-url="C:\WINDOWS\Fonts\SimHei.ttf">
<font-triplet name="SimHei" style="normal" weight="normal"/>
</font>
<!-- 中文字型:宋體 -->
<font metrics-url="out/SimSun.xml" kerning="yes" embed-url="C:\WINDOWS\Fonts\SimSun.ttc">
<font-triplet name="SimSun" style="normal" weight="normal"/>
</font>
<!-- 英文字型:Times New Roman -->
<font metrics-url="out/TimesNewRoman.xml" kerning="yes" embed-url="C:\WINDOWS\Fonts\Times.ttf">
<font-triplet name="TimesNewRoman" style="normal" weight="normal"/>
</font>
</fonts>
</renderer>
修改 Ant 腳本,為 Fop 添加 userconfig 選項,userconfig 指定使用自定義的配置檔案。
<fop format="application/pdf" fofile="${out.dir}/index.fo"
outfile="${out.dir}/index.pdf" userconfig="${src.dir}/fop.xconf" />
5.3. 自定義樣式表
建立 xsl 檔案,命名為
fo.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:include href="../docbook-xsl-1.78.1/fo/docbook.xsl"/>
<!-- 打開擴充功能,可生成PDF書簽 -->
<xsl:param name="fop1.extensions" select="1"></xsl:param>
<!-- 設定文字字型 -->
<xsl:param name="body.font.family">SimSun,TimesNewRoman</xsl:param> <!-- font family for body text -->
<xsl:param name="dingbat.font.family">SimSun,TimesNewRoman</xsl:param> <!-- font family for copyright, quotes, and other symbols -->
<xsl:param name="monospace.font.family">SimSun,TimesNewRoman</xsl:param> <!-- font family for monospace environments -->
<xsl:param name="sans.font.family">SimSun,TimesNewRoman</xsl:param> <!-- sans-serif font family -->
<xsl:param name="title.font.family">SimSun,TimesNewRoman</xsl:param> <!-- font family for titles -->
<xsl:param name="symbol.font.family">Symbol,ZapfDingbats</xsl:param> <!-- font families to be searched for symbols outside of the body font -->
<!-- 段落文字采用左對齊 -->
<xsl:param name="alignment">left</xsl:param>
</xsl:stylesheet>
注意 |
...
<property name="fo.stylesheet" value="${src.dir}/fo.xsl" />
...