天天看點

DocBook中文支援

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 編碼的形式儲存, 例如“中文支援”被存儲成“&#20013;&#25991;&#25903;&#25345;”的形式, 這不影響浏覽器對中文字元的解析,但是占用更多的存儲空間,生成的 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" />
    ...