2013年8月3日 星期六

將 DocBook 轉換成 PDF 格式

這是上一篇文章「DocBook 的 Line Numbering 和 Code Highlighting」的續集,今天我們要將 DocBook 輸出為 PDF 格式,但在這邊要先提醒一下:Apache FOP 似乎不認得 xslthl 轉出來的 tags,所以如果你想將 DocBook 輸出成 PDF,可能就要先放棄 Code HighLighting 的功能。小弟自己在嘗試過多次以後,已經宣告放棄了...XD

我本身使用的 OS 是 Windows 7 Pro 64bit,JVM 版本則是 Oracle JDK 1.6.0_43,建議您盡量採用和我一樣的環境與軟體版本,以免遭遇到其他問題。

接下來進入正題,開始說明轉換的步驟:

一、FOP 的取得、安裝及設定

請到「http://archive.apache.org/dist/xmlgraphics/fop/binaries/」下載 fop-1.0-bin.zip,因為我只試過這個版本,而且沒遇到什麼問題,所以建議您跟我採用一樣的版本吧!

上一篇文章一樣,也請解壓縮在「D:\docbook」下方,所以這個資料夾下方應該要長的像下面這樣才對:
  • docbook-xsl-1.78.1\
  • fop-1.0\
  • output\
  • saxon6-5-5\
  • tools\
  • xerces-2_11_0\
  • xslthl-2.1.0\
  • my_article.xml
  • my_article.xsl
  • my_code.java 
接下來,請修改「D:\docbook\fop-1.0\conf\fop.xconf」的內容,在「renders/render/fonts」區段加入如下內容( START 到 END 之間),讓  FOP 可以使用你系統內的字型(包含中文字型),這部分我是參考「Docbook开发手记」的:

<fop version="1.0">
    ...
  <renderers>
    <renderer mime="application/pdf">
        ...
      <fonts>
        ...
        
        <!-- START -->
         <!-- register all the fonts found in a directory and all of its sub directories (use with care) -->
         <directory recursive="true">file:///c:/windows/fonts/</directory>

         <!-- automatically detect operating system installed fonts -->
         <auto-detect/>
        <!-- END -->
      </fonts>

二、修改 my_article.xsl:

請將 my_article.xsl 替換成如下的內容:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:saxon="http://icl.com/saxon"
                extension-element-prefixes="saxon"
                version='1.0'>
 
<xsl:import href="file:///D:/docbook/docbook-xsl-1.78.1/fo/docbook.xsl"/>
 
<!--=====================================​=======================================
line numbering
====================================================​=========================-->
<xsl:param name="linenumbering.everyNth">1</xsl:param>
<xsl:param name="linenumbering.width">4</xsl:param>
<xsl:param name="linenumbering.separator"><xsl:text> </xsl:text></xsl:param>

<!--====================================================​========================
font setting
====================================================​=========================-->
<xsl:param name="title.font.family">Microsoft JhengHei</xsl:param>
<xsl:param name="body.font.family">Microsoft JhengHei</xsl:param>
<xsl:param name="monospace.font.family">MingLiU</xsl:param>
<xsl:param name="symbol.font.family">Cambria Math</xsl:param>

<!-- add bookmark and support more type of figure -->
<xsl:param name="fop1.extensions">1</xsl:param>

<!-- no indent for body content -->
<xsl:param name="body.start.indent">0pt</xsl:param>

</xsl:stylesheet>

三、使用以下指令進行轉換(在「D:\docbook」下面):

1. 先使用 Saxon 或 Xalan 來產生 fo 檔:

Saxon:
java -cp "D:\docbook\saxon6-5-5\saxon.jar;D:\docbook\docbook-xsl-1.78.1\extensions\saxon65.jar" com.icl.saxon.StyleSheet -o output\my_article.fo my_article.xml my_article.xsl use.extensions=1


Xalan:
java -cp "D:\docbook\tools\xalan.jar;D:\docbook\xerces-2_11_0\xml-apis.jar;D:\docbook\xerces-2_11_0\xercesImpl.jar;D:\docbook\docbook-xsl-1.78.1\extensions\xalan27.jar" org.apache.xalan.xslt.Process -OUT output\my_article.fo -IN my_article.xml -XSL my_article.xsl -L -PARAM use.extensions 1

產生的 fo 檔案位於「D:\docbook\output\my_article.fo」。

2. 再以 fop.bat 指令將 fo 檔轉成  PDF 檔:

fop-1.0\fop.bat -c d:\docbook\fop-1.0\conf\fop.xconf -fo output\my_article.fo -pdf my_article.pdf

產生的 PDF 檔案在「D:\docbook\my_article.pdf」。在執行的過程中,我是有看到一些錯誤訊息(請參考本文最下方),但是最終產生的 PDF 看起來是正常的,所以應該沒什麼關係。

我這邊轉出來的檔案就像下面這個樣子,希望你也成功了。


my_article.pdf



上一篇文章遭遇的問題一樣,Xalan 在轉換外部檔案my_code.java」時,即使有在 <textdata> 標籤加上「encoding="UTF-8"」屬性,中文(在註解的位置)仍會變成亂碼,但 Saxon 就不會。

如果您還想更深入瞭解 DocBook ,建議再參考以下這些網站:
總結來說,DocBook 確實是一套很不錯的文件格式標準(可以轉換成不同的文件格式),個人認為比較可惜的是:(1) 許多相關的文件與資料都已經很舊、過時了,(2) 相關的社群似乎也不再熱絡了。所以每次遇到問題時、要找答案或解決方式,都很困難...

附錄、執行 FOP 時看到的錯誤訊息

D:\docbook>fop-1.0\fop.bat -c d:\docbook\fop-1.0\conf\fop.xconf -fo output\my_ar
ticle.fo -pdf my_article.pdf
2013/8/3 下午 04:53:55 org.apache.fop.apps.FopFactoryConfigurator configure
資訊: Default page-height set to: 11in
2013/8/3 下午 04:53:55 org.apache.fop.apps.FopFactoryConfigurator configure
資訊: Default page-width set to: 8.26in
2013/8/3 下午 04:53:56 org.apache.fop.events.LoggingEventListener processEvent
警告: Font "Cambria Math,normal,700" not found. Substituting with "Cambria Math,
normal,400".
2013/8/3 下午 04:53:57 org.apache.fop.hyphenation.Hyphenator getHyphenationTree
嚴重的: Couldn't find hyphenation pattern zh_tw
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: This is a TrueType collection file with 3 fonts
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: Containing the following fonts:
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU <-- selected
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: PMingLiU
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU_HKSCS
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: This is a TrueType collection file with 3 fonts
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: Containing the following fonts:
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU <-- selected
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: PMingLiU
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU_HKSCS

沒有留言:

張貼留言